View 1991254_293942.PDF datasheet online --- IC-ON-LINE

Datasheet File OCR Text:

Spectra-622 (PM5313) Driver Manual
PM5313
SPECTRA-622
SONET/SDH PAYLOAD EXTRACTOR/ALIGNER FOR 622 MBIT/S
DRIVER MANUAL
DOCUMENT ISSUE 2 ISSUED NOVEMBER, 2000
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
Spectra-622 (PM5313) Driver Manual
ABOUT THIS MANUAL AND SPECTRA-622
This manual describes the SPECTRA-622 device driver. It describes the driver's functions, data structures, and architecture. This manual focuses on the driver's interfaces to your application, real-time operating system, and the devices. It also describes in general terms how to modify and port the driver to your software and hardware platform.
Audience
This manual was written for people who need to: * * * Evaluate and test the SPECTRA-622 devices Modify and add to the SPECTRA-622 driver's functions Port the SPECTRA-622 driver to a particular platform.
References
For more information about the SPECTRA-622 driver, see the driver's release notes. For more information about the SPECTRA-622 device, see the documents listed in Table 1 and any related errata documents. Table 1: Related Documents Document Name SPECTRA-622 Telecom Standard Product Data Sheet PM5313 SPECTRA-622 SONET/SDH Payload Extractor/Aligner for 622 Mbit/s Interfaces Short Form Data Sheet Document Number PMC-1981162
PMC-1981271
Note: Ensure that you use the document that PMC-Sierra issued for your version of the device and driver.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
2
Spectra-622 (PM5313) Driver Manual
Revision History
Issue No. Issue 1 Issue 2 Issue Date Details of Change
December 1999 Document created November 2000 1) Modified the alarm, status and statistics architecture (structures and APIs): a) removed MSB and DSB structures as well as spectraClearStats() API since statistics are no longer accumulated inside the driver. b) Added SPE_STATUS_XX and SPE_CNT_XX structures to add granularity. c) replaced spectraGetStats() API with spectraGetCntXX() and spectraGetStatusXX() APIs. 2) Modified "normal mode" initialization profile in section 4.2: a) replaced serialMode, stm1Mode and ds3Mode fields with 3 new fields: lineSideMode, sysSideMode and clock77 to allow for a better initialization of the IO interface. b) replaced master[4][3] field with sts12c and sts3c[4] for easier configuration of concatenated payloads. 3) Added spectraTOCReadS1 to read the received S1 byte. 4) Removed spectraRPPSDiagPJ and spectraTPPSDiagPJ APIs since the feature is not available in hardware. 5) Fixed incorrect descriptions throughout the document: a) added missing cfgCnt field in DDB structure. b) added missing tppsIllreq[4][3] in ISR mask structure. c) removed rppsCdiff[4][3] and tppsBlkBip[4][3] from
CFG_CNT.
d) added missing au3 parameter description in
spectraDPGMGenRegen.
e) fixed function table description of spectraISR. f) valid states for spectraDiagTestReg now show as PRESENT only. 6) Fixed various typos and formatting issues.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
3
Spectra-622 (PM5313) Driver Manual
Legal Issues
None of the information contained in this document constitutes an express or implied warranty by PMC-Sierra, Inc. as to the sufficiency, fitness or suitability for a particular purpose of any such information or the fitness, or suitability for a particular purpose, merchantability, performance, compatibility with other parts or systems, of any of the products of PMC-Sierra, Inc., or any portion thereof, referred to in this document. PMC-Sierra, Inc. expressly disclaims all representations and warranties of any kind regarding the contents or use of the information, including, but not limited to, express and implied warranties of accuracy, completeness, merchantability, fitness for a particular use, or non-infringement. In no event will PMC-Sierra, Inc. be liable for any direct, indirect, special, incidental or consequential damages, including, but not limited to, lost profits, lost business or lost data resulting from any use of or reliance upon the information, whether or not PMC-Sierra, Inc. has been advised of the possibility of such damage. The information is proprietary and confidential to PMC-Sierra, Inc., and for its customers' internal use. In any event, no part of this document may be reproduced in any form without the express written consent of PMC-Sierra, Inc. (c) 2000 PMC-Sierra, Inc. PMC-1991254 (R2), ref 990876 (R3)
Contacting PMC-Sierra
PMC-Sierra, Inc. 105-8555 Baxter Place Burnaby, BC Canada V5A 4V7 Tel: (604) 415-6000 Fax: (604) 415-6200 Document Information: document@pmc-sierra.com Corporate Information: info@pmc-sierra.com Technical Support: apps@pmc-sierra.com Web Site: http://www.pmc-sierra.com
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
4
Spectra-622 (PM5313) Driver Manual
TABLE OF CONTENTS
About this Manual and SPECTRA-622 ...............................................................................2 Table of Contents.................................................................................................................5 List of Figures .................................................................................................................... 11 List of Tables......................................................................................................................12 1 2 3 Driver Porting Quick Start ...........................................................................................13 Driver Functions and Features ...................................................................................14 Software Architecture..................................................................................................16 3.1 Driver External Interfaces..................................................................................16 Application Programming Interface ............................................................16 Real-Time OS Interface ..............................................................................17 Driver Hardware Interface ..........................................................................17 Main Components .............................................................................................17 Alarms, Status and Statistics ......................................................................19 Input / Output (IO).......................................................................................19 Transport Overhead Controller (TOC) ........................................................19 Receive / Transmit Section Overhead Processor (RSOP/TSOP) ..............20 SONET / SDH Section Trace Buffer (SSTB) ..............................................20 Receive / Transmit Line Overhead Processor (RLOP/TLOP) ....................20 Receive Path Processing Slice (RPPS) .....................................................20 Transmit Path Processing Slice (TPPS).....................................................20 Ring Control Ports (RING) ..........................................................................20 WAN Synchronization Controller (WANS) ..................................................20 DROP Bus PRBS Generator and Monitor (DPGM)....................................21 ADD Bus PRBS Generator and Monitor (APGM).......................................21 Module Data Block (MDB) ..........................................................................21 Device Data Blocks (DDB) .........................................................................21 Interrupt Service Routine............................................................................21 Deferred Processing Routine .....................................................................21 Software States .................................................................................................22 Module States .............................................................................................22 Device States..............................................................................................23 Processing Flows ..............................................................................................24 Module Management..................................................................................24 Device Management...................................................................................25 Interrupt Servicing .............................................................................................26 Calling spectraISR ......................................................................................26 Calling spectraDPR ....................................................................................27 Calling spectraPoll ......................................................................................28
3.2
3.3
3.4
3.5
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
5
Spectra-622 (PM5313) Driver Manual
4
Data Structures ...........................................................................................................29 4.1 4.2 Constants ..........................................................................................................29 Structures Passed by the Application................................................................29 Module Initialization Vector: MIV ................................................................29 Device Initialization Vector: DIV..................................................................30 Initialization Profile: INIT_PROF.................................................................31 Diagnostic Profile: DIAG_PROF.................................................................35 ISR Enable/Disable Mask...........................................................................37 Structures in the Driver's Allocated Memory .....................................................41 Module Data Block: MDB ...........................................................................41 Device Data Block: DDB.............................................................................42 Statistic Counter Configuration (CFG_CNT) ..............................................50 Statistic Counters (CNT).............................................................................51 Structures Passed Through RTOS Buffers .......................................................54 Interrupt Service Vector: ISV ......................................................................54 Deferred Processing Vector: DPV ..............................................................54 Global Variable ..................................................................................................55
4.3
4.4
4.5 5
Application Programming Interface.............................................................................56 5.1 Module Initialization...........................................................................................56 Opening the Driver Module: spectraModuleOpen ......................................56 Closing the Driver Module: spectraModuleClose .......................................56 Module Activation ..............................................................................................57 Starting the Driver Module: spectraModuleStart.........................................57 Stopping the Driver Module: spectraModuleStop .......................................57 Profile Management ..........................................................................................58 Initialization Profile......................................................................................58 Creating an Initialization Profile: spectraAddInitProfile...............................58 Retrieving an Initialization Profile: spectraGetInitProfile.............................59 Deleting an Initialization Profile: spectraDeleteInitProfile...........................59 Diagnostic Profile........................................................................................60 Creating a Diagnostic Profile: spectraAddDiagProfile ................................60 Retrieving a Diagnostic Profile: spectraGetDiagProfile ..............................60 Deleting a Diagnostic Profile: spectraDeleteDiagProfile ............................61 Device Addition and Deletion ............................................................................61 Adding a Device: spectraAdd .....................................................................61 Deleting a Device: spectraDelete ...............................................................62 Device Initialization ...........................................................................................63 Initializing a Device: spectraInit ..................................................................63 Updating the Configuration of a Device: spectraUpdate ............................63 Resetting a Device: spectraReset ..............................................................64 Device Activation and De-Activation .................................................................64
5.2
5.3
5.4
5.5
5.6
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
6
Spectra-622 (PM5313) Driver Manual
Activating a Device: spectraActivate ..........................................................64 DeActivating a Device: spectraDeActivate .................................................65 5.7 Device Reading and Writing..............................................................................66 Reading from a Device Register: spectraRead ..........................................66 Writing to a Device: spectraWrite ...............................................................66 Reading a Block of Registers: spectraReadBlock.....................................67 Writing a Block of Registers: spectraWriteBlock ........................................68 Transport Overhead Controller (TOC) ..............................................................68 Modifying the Z0 Byte: spectraTOCWriteZ0...............................................68 Modifying the S1 Byte: spectraTOCWriteS1 ..............................................69 Reading the S1 Byte: spectraTOCReadS1 ................................................69 Receive / Transmit Section Overhead Processor (RSOP/TSOP).....................70 Forcing Out-of-Frame: spectraSOPForceOOF ..........................................70 Inserting Line AIS: spectraSOPInsertLineAIS ............................................71 Forcing Errors in the A1 Byte: spectraSOPDiagFB ....................................71 Forcing Errors in the B1 Byte: spectraSOPDiagB1 ....................................72 Forcing Loss-Of-Signal: spectraSOPDiagLOS...........................................72
5.8
5.9
5.10 SONET / SDH Section Trace Buffer (SSTB).....................................................73 Retrieving and Setting the Section Trace Messages: spectraSectionTraceMsg .....................................................................73 5.11 Receive / Transmit Line Overhead Processor (RLOP/TLOP)...........................73 Inserting Line Remote Defect Indication: spectraLOPInsertLineRDI .........73 Forcing Errors in the B2: spectraLOPDiagB2.............................................74 Reading the Received K1 and K2 Bytes: spectraLOPReadK1K2..............75 Writing the Transmitted K1 and K2 Bytes: spectraLOPWriteK1K2 ............75 5.12 Receive Path Processing Slice (RPPS)............................................................76 Retrieving and Setting the Path Trace Messages: spectraPathTraceMsg.76 Forcing Loss-Of-Pointer: spectraRPPSDiagLOP .......................................76 Forcing Errors in the H4 Byte: spectraRPPSDiagH4 .................................77 Forcing Tributary Path AIS: spectraRPPSInsertTUAIS ..............................78 Forcing DS3 AIS: spectraRPPSDs3AisGen ...............................................78 5.13 Transmit Path Processing Slice (TPPS) ...........................................................79 Forcing Path AIS: spectraTPPSInsertPAIS ................................................79 Forcing Errors in the B3 Byte: spectraTPPSDiagB3 ..................................80 Forcing a Pointer Value: spectraTPPSForceTxPtr .....................................80 Writing the New Data Flag Bits: spectraTPPSInsertNDF...........................81 Writing the Path Remote Error Indication Count: spectraTPPSInsertPREI81 Forcing Errors in the H4 Byte: spectraTPPSDiagH4..................................82 Forcing Tributary Path AIS: spectraRPPSInsertTUAIS ..............................83 Forcing DS3 AIS: spectraTPPSDs3AisGen ...............................................83 Writing the J1 Byte: spectraTPPSWriteJ1 ..................................................84 Writing the C2 Byte: spectraTPPSWriteC2 ................................................84 Writing the F2 Byte: spectraTPPSWriteF2 .................................................85 Writing the Z3 Byte: spectraTPPSWriteZ3 .................................................86 Writing the Z4 Byte: spectraTPPSWriteZ4 .................................................86 Writing the Z5 Byte: spectraTPPSWriteZ5 .................................................87
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
7
Spectra-622 (PM5313) Driver Manual
5.14 Ring Control Ports (RING) ................................................................................87 Sending Line AIS Maintenance Signal: spectraRINGLineAISControl ........87 Sending Line RDI Maintenance Signal: spectraRINGLineRDIControl .......88 5.15 WAN Synchronization Controller (WANS) ........................................................88 Forcing Phase Reacquisitions: spectraWANSForceReac..........................88 5.16 DROP Bus and ADD Bus PRBS Monitor and Generator (DPGM & APGM) ....89 Configuring Diagnostics: spectraDiagCfg...................................................89 5.17 DPGM Functions...............................................................................................90 Forcing Generation of a New PRBS: spectraDPGMGenRegen ................90 Forcing Bit Errors: spectraDPGMGenForceErr ..........................................90 Forcing a Resynchronization: spectraDPGMonResync .............................91 5.18 APGM Functions ...............................................................................................92 Forcing Generation of a New PRBS: spectraAPGMGenRegen.................92 Forcing Bit Errors: spectraAPGMGenForceErr ..........................................92 Forcing a Resynchronization: spectraAPGMonResync .............................93 5.19 Interrupt Service Functions ...............................................................................93 Getting the Interrupt Mask: spectraGetMask..............................................93 Setting the Interrupt Mask: spectraSetMask ..............................................94 Clearing the Interrupt Mask: spectraClearMask .........................................95 Polling Interrupt Status Registers: spectraPoll ...........................................95 Interrupt Service Routine: spectraISR ........................................................96 Deferred Processing Routine: spectraDPR................................................96 5.20 Alarm, Status and Statistics Functions ..............................................................97 Configuring Statistical Counts: spectraCfgStats .........................................97 Statistics Collection Routine: spectraGetCnt..............................................97 Retrieving Counter for SOP Block: spectraGetCntSOP .............................98 Retrieving Counter for LOP Block: spectraGetCntLOP..............................98 Retrieving Counter for RPPS Block: spectraGetCntRPPS.........................99 Retrieving Counter for TPPS Block: spectraGetCntTPPS .......................100 Retrieving Counter for Pointer Justifications: spectraGetCntPJ...............100 Retrieving Alarm Status: spectraGetStatus ..............................................101 Retrieving Alarm Status for IO block: spectraGetStatusIO .......................102 Retrieving Alarm Status for SOP block: spectraGetStatusSOP................102 Retrieving Alarm Status for LOP block: spectraGetStatusLOP ................103 Retrieving Alarm Status for RPPS block: spectraGetStatusRPPS ...........104 Retrieving Alarm Status for TPPS block: spectraGetStatusTPPS ............104 5.21 Device Diagnostics..........................................................................................105 Verifying Register Access: spectraTestReg..............................................105 Clearing and Setting a Line Loopback: spectraLoopLine.........................105 Clearing and Setting a Serial Loopback: spectraLoopSerialDiag ............106 Clearing and Setting a Parallel Loopback: spectraLoopParaDiag ...........107 Clearing and Setting a System-Side Loopback: spectraLoopSysSideLine107 Clearing and Setting a DS3 Line Loopback: spectraLoopDS3Line..........108 5.22 Callback Functions..........................................................................................109 Callbacks Due to IO Events: cbackSpectraIO ..........................................109
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
8
Spectra-622 (PM5313) Driver Manual
Callbacks Due to TOC Events: cbackSpectraTOC................................... 110 Callbacks Due to SOP Events: cbackSpectraSOP .................................. 110 Callbacks Due to SSTB Events: cbackSpectraSSTB............................... 111 Callbacks Due to LOP Events: cbackSpectraLOP ................................... 111 Callbacks Due to RPPS Events: cbackSpectraRPPS .............................. 112 Callbacks due to TPPS events: cbackSpectraTPPS................................ 113 Callbacks Due to WANS Events: cbackSpectraWANS ............................ 113 Callbacks Due to DPGM Events: cbackSpectraDPGM ............................ 114 Callbacks Due to APGM Events: cbackSpectraAPGM............................. 114 6 Hardware Interface ................................................................................................... 116 6.1 Device I/O........................................................................................................ 116 Reading Registers: sysSpectraRead........................................................ 116 Writing Values: sysSpectraWrite............................................................... 116 Interrupt Servicing ........................................................................................... 117 Installing the ISR Handler: sysSpectraISRHandlerInstall ......................... 117 ISR Handler: sysSpectraISRHandler........................................................ 118 Removing Handlers: sysSpectraISRHandlerRemove .............................. 118 DPR Task: sysSpectraDPRTask ............................................................... 119
6.2
7
RTOS Interface .........................................................................................................120 7.1 Memory Allocation / De-Allocation ..................................................................120 Allocating Memory: sysSpectraMemAlloc ................................................120 Freeing Memory: sysSpectraMemFree ....................................................120 Buffer Management.........................................................................................121 Starting Buffer Management: sysSpectraBufferStart ................................121 Getting DPV Buffers: sysSpectraDPVBufferGet.......................................121 Getting ISV Buffers: sysSpectraISVBufferGet..........................................122 Returning DPV Buffers: sysSpectraDPVBufferRtn...................................122 Returning ISV Buffers: sysSpectraISVBufferRtn ......................................123 Stopping Buffer Management: sysSpectraBufferStop ..............................123 Preemption ......................................................................................................124 Disabling Preemption: sysSpectraPreemptDisable ..................................124 Re-Enabling Preemption: sysSpectraPreemptEnable..............................124 Timers .............................................................................................................125 Suspending a Task Execution: sysSpectraTimerSleep ............................125
7.2
7.3
7.4
8
Porting Drivers ..........................................................................................................126 8.1 8.2 Driver Source Files..........................................................................................126 Driver Porting Procedures...............................................................................127 Step 1: Porting the RTOS interface ..........................................................127 Step 2: Porting the Hardware Interface ....................................................129 Step 3: Porting the Application-Specific Elements....................................130 Step 4: Building the Driver ........................................................................130
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
9
Spectra-622 (PM5313) Driver Manual
Appendix A: Driver Return Codes ...................................................................................131 Appendix B: Coding Conventions....................................................................................132 Macros ......................................................................................................133 Constants..................................................................................................133 Structures..................................................................................................133 Functions ..................................................................................................134 Variables ...................................................................................................134 API Files ...................................................................................................135 Hardware Dependent Files.......................................................................135 Other Driver Files......................................................................................136 List of Terms ....................................................................................................................137 Acronyms.........................................................................................................................138 INDEX..............................................................................................................................139
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
10
Spectra-622 (PM5313) Driver Manual
LIST OF FIGURES
Figure 1: Driver Interfaces.................................................................................................16 Figure 2: Driver Architecture..............................................................................................19 Figure 3: Driver Software States .......................................................................................22 Figure 4: Module Management Flow Diagram ..................................................................24 Figure 5: Device Management Flow Diagram...................................................................25 Figure 6: Interrupt Service Model ......................................................................................26 Figure 7: Polling Service Model.........................................................................................28
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
11
Spectra-622 (PM5313) Driver Manual
LIST OF TABLES
Table 1: Driver Functions and Features ............................................................................14 Table 2: Module Initialization Vector: sSPE_MIV ..............................................................30 Table 3: Device Initialization Vector: sSPE_DIV................................................................30 Table 4: Initialization Profile: sSPE_INIT_PROF...............................................................32 Table 5: Initialization Data: sSPE_INIT_DATA_NORM .....................................................33 Table 6: Initialization Data: sSPE_INIT_DATA_COMP......................................................34 Table 7: Initialization Data: sSPE_INIT_DATA_FRM.........................................................34 Table 8: Diagnostic Profile: sSPE_DIAG_PROF...............................................................35 Table 9: Diagnostic Data: sSPE_DIAG_DATA_NORM .....................................................36 Table 10: Diagnostic Data: sSPE_DIAG_DATA_COMP....................................................36 Table 11: Diagnostic Data: sSPE_DIAG_DATA_FRM.......................................................37 Table 12: ISR Mask: sSPE_MASK ....................................................................................37 Table 13: Module Data Block: sSPE_MDB........................................................................41 Table 14: Device Data Block: sSPE_DDB.........................................................................42 Table 15: Input/Output Status: sSPE_STATUS_IO ...........................................................44 Table 16: Counters Config: sSPE_CFG_CNT...................................................................50 Table 17: Statistic Counters: sSPE_STAT_CNT ...............................................................52 Table 18: Section Overhead Statistics Counters: sSPE_STAT_CNT_SOP ......................52 Table 19: Line Overhead Statistic Counters: sSPE_STAT_CNT_LOP .............................52 Table 20: SPECTRA-622 Receive Path Processing Statistics Counters: sSPE_STAT_CNT_RPPS ...........................................................................................53 Table 21: Transmit Path Processing Statistics Counters: STAT_CNT_TPPS ...................53 Table 22: Pointer Justification Statistics Counters: STAT_CNT_PJ ..................................54 Table 23: Interrupt Service Vector: sSPE_ISV ..................................................................54 Table 24: Deferred Processing Vector: sSPE_DPV ..........................................................55 Table 25: Return Codes...................................................................................................131 Table 26: Variable Type Definitions .................................................................................132 Table 27: Naming Conventions .......................................................................................132 Table 28: File Naming Conventions.................................................................................135
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
12
Spectra-622 (PM5313) Driver Manual Driver Porting Quick Start
1
DRIVER PORTING QUICK START
This section summarizes how to port the SPECTRA-622 device driver to your hardware and operating system (OS) platform. For more information about porting the SPECTRA622 driver, see section 8 (page 126). Note: Because each platform and application is unique, this manual can only offer guidelines for porting the SPECTRA-622 driver. The code for the SPECTRA-622 driver is organized into C source files. You may need to modify the code or develop additional code. The code is in the form of constants, macros, and functions. For the ease of porting, the code is grouped into source files (src) and include files (inc). The source files contain the functions and the include files contain the constants and macros. To port the SPECTRA-622 driver to your platform: Step 1: Port the driver's RTOS interface (page 127): Data types OS-specific services Utilities and interrupt services that use OS-specific services
Step 2: Port the driver's hardware interface (page 129) Port low-level device read-and-write macros. Define hardware system-configuration constants.
Step 3: Port the driver's application-specific elements (page 130): Define the task-related constants. Code the callback functions.
Step 4: Build the driver (page 130).
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
13
Spectra-622 (PM5313) Driver Manual Driver Functions and Features
2
DRIVER FUNCTIONS AND FEATURES
This section describes the main functions and features supported by the SPECTRA-622 driver. Table 1: Driver Functions and Features Function Open / Close Driver Module (page 56) Description Opening the Driver Module allocates all the memory needed by the driver and initializes all Module level data structures. Closing the Driver Module shuts down the driver module gracefully after deleting all devices that are currently registered with the driver, and releases all the memory allocated by the driver. Starting the Driver Module involves allocating all RTOS resources needed by the driver such as timers and semaphores (except for memory, which is allocated during the Open call). Closing the Driver Module involves de-allocating all RTOS resources allocated by the driver without changing the amount of memory allocated to it. Add / Delete Device (page 61) Adding a device involves verifying that the device exists, associating a device Handle to the device, and storing context information about it. The driver uses this context information to control and monitor the device. Deleting a device involves shutting down the device and clearing the memory used for storing context information about this device. Device Initialization (page 63) Activate / DeActivate Device (page 64) On the contrary, de-activating a device removes it from its operating state, disables interrupts and other global registers. Activating a device puts it into its normal mode of operation by enabling interrupts and other global registers. A successful device activation also enables other API invocations. The initialization function resets then initializes the device and any associated context information about it. The driver uses this context information to control and monitor the SPECTRA-622 device.
Start / Stop Driver Module (page 57)
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
14
Spectra-622 (PM5313) Driver Manual Driver Functions and Features
Read / Write Device Registers (page 66) Interrupt Servicing / Polling (page 93)
These functions provide a `raw' interface to the device. Device registers that are both directly and indirectly accessible are available for both inspection and modification via these functions. If applicable, block reads and writes are also available. Interrupt Servicing is an optional feature. The user can disable device interrupts and instead poll the device periodically to monitor status and check for alarm/error conditions. Both polling and interrupt driven approaches detect a change in device status and report the status to a Deferred Processing Routine (DPR). The DPR then invokes application callback functions based on the status information retrieved. This allows the driver to report significant events that occur within the device to the application. Functions are provided to retrieve a snapshot of the various counts that are accumulated by the SPECTRA-622 device. Routines should be invoked often enough to avoid letting the counters to rollover.
Statistics Collection (page 97)
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
15
Spectra-622 (PM5313) Driver Manual Software Architecture
3
SOFTWARE ARCHITECTURE
This section describes the software architecture of the SPECTRA-622 device driver. This includes a discussion of the driver's external interfaces and its main components.
3.1
Driver External Interfaces
Figure 1 illustrates the external interfaces defined for the SPECTRA-622 device driver. Figure 1: Driver Interfaces
Application
Function Calls
Application Callbacks
Service Callbacks
SPECTRA-622 Device Driver
RTOS
Service Calls
Hardware Interrupts
Register Accesses
SPECTRA-622 Devices
Application Programming Interface
The driver's API is a collection of high level functions that can be called by application programmers to configure, control, and monitor the SPECTRA-622 device, such as: * * * Initializing the device Validating device configuration Retrieving device status and statistics information.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
16
Spectra-622 (PM5313) Driver Manual Software Architecture
*
Diagnosing the device
The driver API functions use the driver library functions as building blocks to provide this system level functionality to the application programmer (see below). The driver API also consists of callback functions that notify the application of significant events that take place within the device and driver, including alarms reporting.
Real-Time OS Interface
The driver's RTOS interface module provides functions that let the driver use RTOS services. The SPECTRA-622 driver requires the memory, interrupt, and preemption services from the RTOS. The RTOS interface functions perform the following tasks for the SPECTRA-622 device and driver: * * * Allocate and de-allocate memory Manage buffers for the ISR and DPR Disable and enable preemption
The RTOS interface also includes service callbacks. These are functions installed by the driver using RTOS service calls, such as installing the ISR handler and the DPR task. These service callbacks are invoked when an interrupt occurs or the DPR is scheduled. Note: You must modify RTOS interface code to suit your RTOS.
Driver Hardware Interface
The SPECTRA-622 hardware interface provides functions that read from and write to device-registers. The hardware interface also provides a template for an ISR that the driver calls when the device raises a hardware interrupt. You must modify this function based on the interrupt configuration of your system.
3.2
Main Components
Figure 2 illustrates the top-level architectural components of the SPECTRA-622 device driver. This applies in both polled and interrupt driven operation. In polled operation the ISR is called periodically. In interrupt operation the interrupt directly triggers the ISR. The driver includes the following main components: * * * Module and Device(s) Data-Blocks Interrupt-Processing Routine Deferred-Processing Routine
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
17
Spectra-622 (PM5313) Driver Manual Software Architecture
* * * * * * * * * * * *
Alarm, Status and Statistics Input/Output Transport Overhead Controller Section Overhead Processor SONET/SDH Section Trace Buffer Line Overhead Processor Receive Path Processing Slice Transmit Path Processing Slice Ring Control Ports WAN Synchronization Controller DROP Bus PRBS Generator and Monitor ADD Bus PRBS Generator and Monitor
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
18
Spectra-622 (PM5313) Driver Manual Software Architecture
Figure 2: Driver Architecture
Application Function Calls Application Callbacks Driver API Alarm, Status & Statistics Input/Output (IO) RING Interrupt Context WANS Transport Overhead Controller Section Overhead Processor RTOS Interface SONET/SDH Section Trace Buffer Line Overhead Processor Receive Path Processing Slice Transmit Path Processing Slice DPGM Hardware Interface Hardware Interrupts Register Accesses SPECTRA-622 Devices APGM Service Callbacks Service Calls RTOS
Deferred Processing Routine
Module Data Block Device Data Blocks .......
Interrupt Service Routine
Alarms, Status and Statistics
The Alarms, Status and Statistics is responsible for monitoring alarms, tracking devices status information and retrieving statistical counts for each device registered with (added to) the driver.
Input / Output (IO)
The Input / Output section is responsible for configuring the line-side and system-side device interfaces. On the line-side, functions are provided to control the 622.08 Mbps clock/data interface. On the system-side, in Telecom Bus mode functions are provided to control the Add/Drop Telecom Bus data interfaces and the Time Slot Interchange (TSI). In DS3 mode, functions are provided to control the DS3 data interface.
Transport Overhead Controller (TOC)
The Transport Overhead Controller is responsible for configuring the transport overhead processing on both receive and transmit sides. Functions are provided to directly write the Z0 and S1 bytes.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
19
Spectra-622 (PM5313) Driver Manual Software Architecture
Receive / Transmit Section Overhead Processor (RSOP/TSOP)
The Receive / Transmit Section Overhead Processor is responsible for configuring and monitoring the processing of the section overhead on both receive and transmit sides. Functions are provided to monitor the received section overhead, to enable/disable Line AIS insertion and to enable/disable insertion of section errors for diagnostics.
SONET / SDH Section Trace Buffer (SSTB)
The SONET / SDH Section Trace Buffer is responsible for configuring and monitoring the section trace message (J0). Functions are provided to monitor the received section trace message and set the transmit section message,
Receive / Transmit Line Overhead Processor (RLOP/TLOP)
The Receive / Transmit Line Overhead Processor is responsible for configuring and monitoring the processing of the line overhead on both receive and transmit sides. Functions are provided to monitor the received line overhead, to configure and monitor the RASE (Receive APS Synchronization Extractor), and enable/disable the insertion of line errors for diagnostics. Functions are provided to directly read/write the K1 and K2 bytes.
Receive Path Processing Slice (RPPS)
The Receive Path Processing Slice functions are provided to configure and monitor the RTAL (Receive Telecombus Aligner) and tandem connection, to monitor the received path overhead and path trace message (J1), and to configure the DS3 mapper (D3MD) in DS3 mode.
Transmit Path Processing Slice (TPPS)
The Transmit Path Processing Slice functions are provided to configure and monitor the TTAL (Transmit Telecombus Aligner) and tandem connection, to configure the path overhead, to enable/disable the insertion of path overhead (J1) errors for diagnostics, and to configure the DS3 mapper (D3MA) in DS3 mode. Functions are provided to directly write the J1, C2, F2, Z3, Z4 and Z5 bytes.
Ring Control Ports (RING)
Ring Control Ports functions are provided to enable/disable the generation of the rx/tx ring control port signals.
WAN Synchronization Controller (WANS)
The WAN Synchronization Controller functions are provided to enable/disable the generation of the WAN synchronization signals.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
20
Spectra-622 (PM5313) Driver Manual Software Architecture
DROP Bus PRBS Generator and Monitor (DPGM)
The DROP Bus PRBS Generator and Monitor functions are provided to enable / disable the insertion of a pseudo random byte sequence inside the payload.
ADD Bus PRBS Generator and Monitor (APGM)
The ADD bus PRBS Generator and Monitor functions are provided to enable / disable the insertion of a pseudo random byte sequence inside the payload.
Module Data Block (MDB)
The Module Data Block (MDB) is the top-layer data structure, created by the SPECTRA622 device driver to keep track of its initialization and operating parameters, modes and dynamic data. The MDB is allocated via an RTOS call, when the driver module is opened and contains all the device structures
Device Data Blocks (DDB)
The Device Data Blocks (DDB) are contained in the MDB and they are allocated when the module is opened. They are initialized by the SPECTRA-622 device driver for each device that is registered, to keep track of that device's initialization and operating parameters, modes and dynamic data. There is a limit on the number of devices that can be registered with the driver module. This number is set when the driver module is opened.
Interrupt Service Routine
The SPECTRA-622 driver provides an ISR called spectraISR that checks if there are any valid interrupt conditions present for the device. This function can be used by a system-specific interrupt-handler function to service interrupts raised by the device. The low-level interrupt-handler function that traps the hardware interrupt and calls spectraISR is system and RTOS dependent. Therefore, it is outside the scope of the driver. Example implementations of an interrupt handler and functions that install and remove it are provided as a reference on page 117. You can customize these example implementations to suit your specific needs.
Deferred Processing Routine
The DPR provided by the SPECTRA-622 driver (spectraDPR) clears and processes interrupt conditions for the device. Typically, a system specific function, which runs as a separate task within the RTOS, executes the DPR. See page 26 for a detailed explanation of the DPR and interrupt-servicing model.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
21
Spectra-622 (PM5313) Driver Manual Software Architecture
3.3
Software States
Figure 3 shows the software state diagram for the SPECTRA-622 driver. State transitions occur on the successful execution of the corresponding transition functions shown. State information helps maintain the integrity of the MDB and DDB(s) by controlling the set of operations allowed in each state. Figure 3: Driver Software States
spectraModuleOpen Idle spectraModuleClose Start
spectraModuleStop
spectraModuleStart
spectraModuleClose
Ready
MODULE STATES
Start
spectraAdd
spectraDelete
Present spectraReset spectraInit spectraActivate Inactive spectraDeActivate PER-DEVICE STATES Active spectraReset
Module States
The following is a description of the SPECTRA-622 module states. See sections 5.1 and 5.2 for a detailed description of the API functions that are used to change the module state.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
22
Spectra-622 (PM5313) Driver Manual Software Architecture
Start The driver Module has not been initialized. In this state the driver does not hold any RTOS resources (memory, timers, etc); has no running tasks, and performs no actions. Idle The driver Module has been initialized successfully. The Module Initialization Vector (MIV) has been validated, the Module Data Block (MDB) has been allocated and loaded with current data, the per-device data structures have been allocated, and the RTOS has responded without error to all the requests sent to it by the driver. Ready This is the normal operating state for the driver Module. This means that all RTOS resources have been allocated and the driver is ready for Devices to be added. The driver Module remains in this state while Devices are in operation.
Device States
The following is a description of the SPECTRA-622 per-device states. The state that is mentioned here is the software state as maintained by the driver, and not as maintained inside the device itself. See sections 5.4, 5.5 and 5.6 for a detailed description of the API functions that are used to change the per-device state. Start The Device has not been initialized. In this state the device is unknown by the driver and performs no actions. There is a separate flow for each device that can be added, and they all start here. Present The Device has been successfully added. A Device Data Block (DDB) has been associated to the Device and updated with the user context, and a device handle has been given to the USER. In this state, the device performs no actions. Inactive In this state the Device is configured but all data functions are de-activated including interrupts and alarms, status and statistics functions. Active This is the normal operating state for the Device. In this state, interrupt servicing or polling is enabled.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
23
Spectra-622 (PM5313) Driver Manual Software Architecture
3.4
Processing Flows
This section describes the main processing flows of the SPECTRA-622 driver modules. The flow diagrams presented here illustrate the sequence of operations that take place for different driver functions. The diagrams also serve as a guide to the application programmer by illustrating the sequence in which the application must invoke the driver API.
Module Management
The following diagram illustrates the typical function call sequences that occur when initializing or shutting down the SPECTRA-622 driver module. Figure 4: Module Management Flow Diagram
START Performs module level initialization of the driver. Validates the Module Initialization Vector (MIV). Allocates memory for the MDB and all its components (i.e. all the memory needed by the driver) and then initializes the contents of the MDB with the validated MIV. Performs module level startup of the driver. This involves allocating RTOS resources such as semaphores and timers and installing the ISR handler and DPR task. Register an initialization or diagnostic profile. This allows the user to store pre-defined parameter vectors that are validated ahead of time. When the device-initialization function is invoked only a profile number need to be passed. This method simplifies and expedites the above operations. Perform all device level functions here (add, init, activate, de-activate, reset, delete,...) spectraDeleteInitProfile spectraDeleteDiagPrfile De-register an initialization or diagnostic profile previously registered with the driver.
spectraModuleOpen
spectraModuleStart
spectraAddInitProfile spectraAddDiagProfile
spectraModuleStop
Performs Module level shutdown of the driver. This involves deleting all devices currently installed and de-allocating all timers and semaphores as well as removing the ISR handler and DPR task.
spectraModuleClose
Performs module level shutdown of the driver. De-allocates all the driver's memory.
END
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
24
Spectra-622 (PM5313) Driver Manual Software Architecture
Device Management
The following diagram shows the functions and process that the driver uses to add, initialize, re-initialize, and delete the SPECTRA-622 device. Figure 5: Device Management Flow Diagram
START
spectraAdd
Detects the new device in hardw are, assigns a DDB to the new device and stores the user's context for the device. Returns a device handle to the user. Applies a reset to the device and initializes the device registers and associated RAMs based on the DIV passed by the user. The user may only pass a profile number, w hich corresponds to a previously saved & validated set of configurations (by using spectraAddInitProfile).
spectraInit
spectraActivate
Prepares the device for normal operation by enabling interrupts and other global enables. ISR routines are installed w hen the module is started using sysSpectraISRHandlerInstall. The device is now operational and all other API can be invoked.
spectraReset
In order to re-initialize the device, reset the device using spectraReset and go through the initialization sequence again.
spectraDeActivate
De-activates the device and removes it from normal operation. This involves disabling the device interrupts. ISR routines for this device are removed using sysSpectraISRHandlerRemove w hen the module is closed. Applies a softw are reset to the device to put it in its default startup state.
spectraReset
spectraDelete
Removes the device from the list of devices being controlled by the SPECTRA-622 driver. This function de-allocates the device context information for the device being deleted.
END
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
25
Spectra-622 (PM5313) Driver Manual Software Architecture
3.5
Interrupt Servicing
The SPECTRA-622 driver services device interrupts using an interrupt service routine (ISR) that traps interrupts and a deferred processing routine (DPR) that actually processes the interrupt conditions and clears them. This lets the ISR execute quickly and exit. Most of the time-consuming processing of the interrupt conditions is deferred to the DPR by queuing the necessary interrupt-context information to the DPR task. The DPR function runs in the context of a separate task within the RTOS. Note: Since the DPR task processes potentially serious interrupt conditions, you should set the DPR task's priority higher than the application task interacting with the SPECTRA-622 driver. The driver provides the system-independent functions, spectraISR and spectraDPR. You must fill in the corresponding system-specific functions, sysSpectraISRHandler and sysSpectraDPRTask. The system-specific functions isolate the system-specific communication mechanism (between the ISR and DPR) from the system-independent functions, spectraISR and spectraDPR. Figure 6 illustrates the interrupt service model used in the SPECTRA-622 driver design. Figure 6: Interrupt Service Model
sysSpectraISRHandler spectraISR Interrupt Context Information sysSpectraDPRTask spectraDPR Indication Callbacks Application
Note: Instead of using an interrupt service model, you can use a polling service model in the SPECTRA-622 driver to process the device's event-indication registers (see page 28).
Calling spectraISR
An interrupt handler function, which is system dependent, must call spectraISR. But first, the low-level interrupt-handler function must trap the device interrupts. You must implement this function to fit your own system. As a reference, an example implementation of the interrupt handler (sysSpectraISRHandler) appears on page 118. You can customize this example implementation to suit your needs. The interrupt handler that you implement (sysSpectraISRHandler) is installed in the interrupt vector table of the system processor. It is called when one or more SPECTRA622 devices interrupt the processor. The interrupt handler then calls spectraISR for each device in the active state that has interrupt processing enabled.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
26
Spectra-622 (PM5313) Driver Manual Software Architecture
The spectraISR function reads from the master interrupt-status registers and the miscellaneous interrupt-status registers of the SPECTRA-622. If at least one valid interrupt condition is found then spectraISR fills an Interrupt Service Vector (ISV) with this status information as well as the current device Handle. The spectraISR function also clears and disables all the device's interrupts detected. The sysSpectraISRHandler function is then responsible to send this ISV buffer to the DPR task. Note: Normally you should save the status information for deferred interrupt processing by implementing a message queue.
Calling spectraDPR
The sysSpectraDPRTask function is a system specific function that runs as a separate task within the RTOS. You should set the DPR task's priority higher than the application task(s) interacting with the SPECTRA-622 driver. In the message-queue implementation model, this task has an associated message queue. The task waits for messages from the ISR on this message queue. When a message arrives, sysSpectraDPRTask calls the DPR (spectraDPR) with the received ISV. Then spectraDPR processes the status information and takes appropriate action based on the specific interrupt condition detected. The nature of this processing can differ from system to system. Therefore, spectraDPR calls different indication callbacks for different interrupt conditions. Typically, you should implement these callback functions as simple message posting functions that post messages to an application task. However, you can implement the indication callback to perform processing within the DPR task context and return without sending any messages. In this case, ensure that the indication function does not call any API functions that change the driver's state, such as spectraDelete. Also, ensure that the indication function is non-blocking because the DPR task executes while SPECTRA622 interrupts are disabled. You can customize these callbacks to suit your system. See page 109 for example implementations of the callback functions. Note: Since the spectraISR and spectraDPR routines themselves do not specify a communication mechanism, you have full flexibility in choosing a communication mechanism between the two. A convenient way to implement this communication mechanism is to use a message queue, which is a service that most RTOSs provide. You must implement the two system specific functions, sysSpectraISRHandler and sysSpectraDPRTask. When the driver calls sysSpectraISRHandlerInstall, the application installs sysSpectraISRHandler in the interrupt vector table of the processor. The sysSpectraDPRTask function is spawned as a task by the application. The sysSpectraISRHandler Install function also creates the communication channel between sysSpectraISRHandler and sysSpectraDPRTask. This communication channel is most commonly a message queue associated with the
sysSpectraDPRTask.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
27
Spectra-622 (PM5313) Driver Manual Software Architecture
Similarly, during removal of interrupts, the driver removes sysSpectraISRHandler from the microprocessor's interrupt vector table and deletes the task associated with
sysSpectraDPRTask.
As a reference, this manual provides example implementations of the interrupt installation and removal functions on page 117. You can customize these prototypes to suit your specific needs.
Calling spectraPoll
Instead of using an interrupt service model, you can use a polling service model in the SPECTRA-622 driver to process the device's event-indication registers. Figure 7 illustrates the polling service model used in the SPECTRA-622 driver design. Figure 7: Polling Service Model
spectraPoll spectraISR Interrupt Context Information spectraDPR Indication Callbacks Application
In polling mode, the application is responsible for calling spectraPoll often enough to service any pending error or alarm conditions. When spectraPoll is called, the spectraISR function is called internally. The spectraISR function reads from the master interrupt-status registers and the miscellaneous interrupt-status registers of the SPECTRA-622. If at least one valid interrupt condition is found then spectraISR fills an Interrupt Service Vector (ISV) with this status information as well as the current device Handle. The spectraISR function also clears and disables all the device's interrupts detected. In polling mode, this ISV buffer is passed to the DPR task by calling spectraDPR internally.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
28
Spectra-622 (PM5313) Driver Manual Data Structures
4
4.1
DATA STRUCTURES
Constants
The following Constants are used throughout the driver code: * error codes used throughout the driver code, returned by the API functions and used in the global error number field of the MDB and DDB. See Appendix A on page 131.
SPE_MAX_DEVS defines the maximum number of devices that can be supported by
*
this driver. This constant must not be changed without a thorough analysis of the consequences to the driver code. * *
SPE_MOD_START, SPE_MOD_IDLE, SPE_MOD_READY are the three possible Module
states (stored in stateModule).
SPE_START, SPE_PRESENT, SPE_ACTIVE, SPE_INACTIVE are the four possible Device states (stored in stateDevice).
4.2
Structures Passed by the Application
These structures are defined for use by the application and are passed as argument to functions within the driver. These structures are the Module Initialization Vector (MIV), the Device Initialization Vector (DIV) and the ISR mask.
Module Initialization Vector: MIV
Passed via the spectraModuleOpen call, this structure contains all the information needed by the driver to initialize and connect to the RTOS. *
maxDevs is used to inform the Driver how many Devices will be operating
concurrently during this session. The number is used to calculate the amount of memory that will be allocated to the driver. The maximum value that can be passed is
SPE_MAX_DEVS.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
29
Spectra-622 (PM5313) Driver Manual Data Structures
Table 2: Module Initialization Vector: sSPE_MIV
Field Name
pmdb maxDevs maxInitProfs maxDiagProfs
Field Type
sSPE_MDB * UINT2 UINT2 UINT2
Field Description
(pointer to) MDB Maximum number of devices supported during this session Maximum number of initialization profiles Maximum number of diagnostic profiles
Device Initialization Vector: DIV
Passed via the spectraInit call, this structure contains all the information needed by the driver to initialize a SPECTRA-622 device. This structure is also passed via the spectraAddInitProfile call when used as an initialization profile. * *
valid indicates that this initialization profile has been properly initialized and may be used by the USER. This field should be ignored when the DIV is passed directly. pollISR is a flag that indicates the type of interrupt servicing the driver is to use.
The choices are `polling' (SPE_POLL_MODE), and `interrupt driven' (SPE_ISR_MODE). When configured in polling the Interrupt capability of the Device is NOT used, and the USER is responsible for calling devicePoll periodically. The actual processing of the event information is the same for both modes. *
cbackIO, cbackTOC, cbackSOP, cbackSSTB, cbackLOP, cbackRPPS, cbackTPPS, cbackWANS, cbackDPGM and cbackAPGM are used to pass the address
of application functions that will be used by the DPR to inform the application code of pending events. If these fields are set as NULL, then any events that might cause the DPR to `call back' the application will be processed during ISR processing but ignored by the DPR. Table 3: Device Initialization Vector: sSPE_DIV
Field Name
valid initMode
Field Type
UINT2 SPE_MODE
Field Description
Indicates that this profile is valid Mode used for Initialization: SPE_NORM, SPE_COMP or SPE_FRM
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
30
Spectra-622 (PM5313) Driver Manual Data Structures
Field Name
pinitData
Field Type
UINT1*
Field Description
(pointer to) initialization data. Depending on the specified mode of initialization, this is in fact a pointer to sSPE_INIT_DATA_NORM, sSPE_INIT_DATA_COMP or
sSPE_INIT_DATA_FRM.
pollISR cbackIO cbackTOC cbackSOP cbackSSTB cbackLOP cbackRPPS cbackTPPS cbackWANS cbackDPGM cbackAPGM
sSPE_POLL sSPE_CBACK sSPE_CBACK sSPE_CBACK sSPE_CBACK sSPE_CBACK sSPE_CBACK sSPE_CBACK sSPE_CBACK sSPE_CBACK sSPE_CBACK
Indicates the type of ISR / polling to do Address for the callback function for IO Events Address for the callback function for TOC Events Address for the callback function for SOP Events Address for the callback function for SSTB Events Address for the callback function for LOP Events Address for the callback function for RPPS Events Address for the callback function for TPPS Events Address for the callback function for WANS Events Address for the callback function for DPGM Events Address for the callback function for APGM Events
Initialization Profile: INIT_PROF
Initialization Profile Top-Level Structure Passed via the spectraAddInitProfile call, this structure contains all the information needed by the driver to initialize and activate a SPECTRA-622 device. This is in fact the same structure as sSPE_DIV.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
31
Spectra-622 (PM5313) Driver Manual Data Structures
Table 4: Initialization Profile: sSPE_INIT_PROF
Field Name
valid initMode
Field Type
UINT2 SPE_MODE
Field Description
Indicates that this profile is valid Mode used for Initialization: SPE_NORM, SPE_COMP or SPE_FRM (pointer to) initialization data. Depending on the specified mode of initialization, this is in fact a pointer to sSPE_INIT_DATA_NORM, sSPE_INIT_DATA_COMP or
sSPE_INIT_DATA_FRM.
pinitData
UINT1*
pollISR cbackIO cbackTOC cbackSOP cbackSSTB cbackLOP cbackRPPS cbackTPPS cbackWANS cbackDPGM cbackAPGM
sSPE_POLL sSPE_CBACK sSPE_CBACK sSPE_CBACK sSPE_CBACK sSPE_CBACK sSPE_CBACK sSPE_CBACK sSPE_CBACK sSPE_CBACK sSPE_CBACK
Indicates the type of ISR / polling to do Address for the callback function for IO Events Address for the callback function for TOC Events Address for the callback function for SOP Events Address for the callback function for SSTB Events Address for the callback function for LOP Events Address for the callback function for RPPS Events Address for the callback function for TPPS Events Address for the callback function for WANS Events Address for the callback function for DPGM Events Address for the callback function for APGM Events
Initialization Data in Normal Mode (SPE_NORM) In Normal mode (NORM), the user only specifies the main modes of operation of the device. Most of the device's register bits are left in their default state (after a software reset). This structure is pointed to by pinitData inside the initialization profile.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
32
Spectra-622 (PM5313) Driver Manual Data Structures
Table 5: Initialization Data: sSPE_INIT_DATA_NORM
Field Name
lineSideMode
Field Type
UINT2
Field Description
selects between serial mode, parallel mode, dual mode with serial input, and dual mode with parallel input on the line side selects between mode selected via DMODE[1:0] inputs, telecom mode, ds3 mode, dual mode w/ telecom bus input, and dual mode w/ds3 input. selects between stm4 and stm1 telecom bus mode on the system side selects the master/slave slices for sts-12/12c mode selects the master/slave slices for sts-3/3c mode enables the ring control ports enables the phase comparison in the wan synchronization controller
sysSideMode
UINT2
clock77 sts12c sts3c[4] ringEna wansEna
UINT2 UINT2 UINT2 UINT2 UINT2
Initialization Data in Compatibility Mode (SPE_COMP) In Compatibility mode (COMP), the user provides a list of data blocks to write directly to the device registers. There are numBlocks blocks provided by the USER. The block number [i] is fully defined by: * * * *
ppblock[i], which points to the data to write to the device's registers ppmask[i], which points to a data mask to specify which bits are to be modified psize[i], the block size pstartReg[i], which is the register number at which the driver should start writing
the data. This structure is pointed to by pinitData inside the initialization profile.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
33
Spectra-622 (PM5313) Driver Manual Data Structures
Table 6: Initialization Data: sSPE_INIT_DATA_COMP
Field Name
numBlocks ppblk[] ppmask[] pblkSize[] pstartReg[]
Field Type
UINT2 UINT1* UINT1* UINT2 UINT2
Field Description
Number of provided blocks (pointer to) an array of pointer to a data block (pointer to) an array of pointer to a mask (pointer to) an array of block size array of register numbers
Initialization Data in Flat Register Mode (SPE_FRM) In Flat Register Mode (FRM), for each of the hardware blocks (IO, TOC, SOP, SSTB, LOP, RPPS, TPPS, RING and WANS), the user needs to fill a structure that holds a mapping of all the configuration bits for this hardware block. They are used to fully configure the SPECRTA-622 device. This structure is pointed to by pinitData inside the initialization profile. The reader is referred to the code for the definitions of the configuration blocks (sSPE_CFG_XXX). Table 7: Initialization Data: sSPE_INIT_DATA_FRM
Field Name
cfgIO cfgTOC cfgSOP
Field Type
sSPE_CFG_IO sSPE_CFG_TOC sSPE_CFG_SOP
Field Description
Input / Output (IO) configuration block Receive / Transmit Transport Overhead Controller (TOC) configuration block Receive / Transmit Section Overhead Processor (RSOP/TSOP) configuration block Sonet/SDH Section Trace Buffer (SSTB) configuration block Receive / Transmit Line Overhead Processor (RLOP/TLOP) configuration block Receive Path Processing Slice (RPPS) configuration block Transmit Path Processing Slice (TPPS) configuration block
cfgSSTB cfgLOP
sSPE_CFG_SSTB sSPE_CFG_LOP
cfgRPPS[4][3] cfgTPPS[4][3]
sSPE_CFG_RPPS sSPE_CFG_TPPS
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
34
Spectra-622 (PM5313) Driver Manual Data Structures
Field Name
cfgRING cfgWANS
Field Type
sSPE_CFG_RING sSPE_CFG_WANS
Field Description
Ring Control Port (RING) configuration block WAN Synchronization controller (WANS) configuration block
Diagnostic Profile: DIAG_PROF
Diagnostic Profile Top-Level Structure Passed via the spectraAddDiagProfile call, this structure contains all the information needed by the driver to initiate a specific diagnostic on the SPECTRA-622 device. *
diagMode is a flag that tells the Driver which diagnostic mode is used to configure
the device. There are three different ways to configure a device for diagnostics, each corresponding to a different mode: Normal Mode (SPE_NORM): the user only specifies the main modes of operation of the DPGM and APGM. Most of the device's register bits are left in their default state (after a software reset). Compatibility mode (SPE_COMP): the user provides a list of data blocks to write directly to the APGM and DPGM registers. Flat Register Mode (SPE_FRM): for each of the 12 DPGM and APGM hardware blocks, the user needs to fill a structure (sSPE_CFG_DPGM and sSPE_CFG_APGM) that holds a mapping of all the configuration bits for this hardware block.

Table 8: Diagnostic Profile: sSPE_DIAG_PROF
Field Name
valid diagMode
Field Type
UINT2 SPE_MODE
Field Description
Indicates that this profile is valid Mode used for diagnostic: SPE_NORM, SPE_COMP or SPE_FRM (pointer to) diagnostic data. Depending on the specified mode of diagnostic, this is in fact a pointer to sSPE_INIT_DATA_NORM, sSPE_INIT_DATA_COMP or
sSPE_INIT_DATA_FRM.
pdiagData
UINT1*
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
35
Spectra-622 (PM5313) Driver Manual Data Structures
Diagnostic Data in Normal Mode: SPE_NORM In Normal mode (NORM), the user only specifies the main modes of operation of the DPGM and APGM. Most of the register bits are left in their default state (after a software reset). This structure is pointed to by pdiagData inside the diagnostic profile. Table 9: Diagnostic Data: sSPE_DIAG_DATA_NORM
Field Name
dpgmGenEna[4][3] dpgmMonEna[4][3] apgmGenEna[4][3] apgmMonEna[4][3]
Field Type
UINT1 UINT1 UINT1 UINT1
Field Description
Enables the Generator of the DROP Bus PRBS Generator and Monitor (DPGM) Enables the Monitor of the DROP Bus PRBS Generator and Monitor (DPGM) Enables the Generator of the ADD Bus PRBS Generator and Monitor (APGM) Enables the Monitor of the ADD Bus PRBS Generator and Monitor (APGM)
Diagnostic Data in Compatibility: Mode SPE_COMP In Compatibility mode (COMP), the user provides a list of data blocks to write directly to the DPGM and APGM registers. There are numBlocks blocks provided by the USER. The block number [i] is fully defined by: * * * *
ppblock[i], which points to the data to write to the device's registers ppmask[i], which points to a data mask to specify which bits are to be modified psize[i], the block size pstartReg[i], which is the register number at which the driver should start writing
the data. This structure is pointed to by pdiagData inside the diagnostic profile. Table 10: Diagnostic Data: sSPE_DIAG_DATA_COMP
Field Name
numBlocks ppblk[] ppmask[] pblkSize[]
Field Type
UINT2 UINT1* UINT1* UINT2
Field Description
number of provided blocks array of pointer to a data block array of pointer to a mask array of block size
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
36
Spectra-622 (PM5313) Driver Manual Data Structures
Field Name
pstartReg[]
Field Type
UINT2
Field Description
array of register numbers
Diagnostic Data in FRM Mode: SPE_FRM In Flat Register Mode (FRM), for each of the 12 DPGM and APGM hardware blocks, the user needs to fill a structure that holds a mapping of all the configuration bits for this hardware block. They are used to fully configure the DPGM and APGM. This structure is pointed to by pdiagData inside the diagnostic profile. The reader is referred to the code for the definitions of the configuration blocks (sSPE_CFG_XXX). Table 11: Diagnostic Data: sSPE_DIAG_DATA_FRM
Field Name
cfgDPGM[4][3] cfgAPGM[4][3]
Field Type
sSPE_CFG_DPGM sSPE_CFG_APGM
Field Description
DROP Bus PRBS Generator and Monitor (DPGM) configuration block ADD Bus PRBS Generator and Monitor (APGM) configuration block
ISR Enable/Disable Mask
Passed via the spectraSetMask, spectraGetMask and spectraClearMask calls, this structure contains all the information needed by the driver to enable and disable any of the interrupts in the SPECTRA-622. Table 12: ISR Mask: sSPE_MASK
Field Name
ioScpife[4] ioScpire[4] ioDool ioCrsiRool ioLos ioCspiRool ioApe[4]
Field Type
UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1
Field Description
Serial control port falling edge Serial control port raising edge Data out of lock (DOOL) Reference out of lock (ROOL) Loss of signal (LOS) Reference out of lock Add bus parity error
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
37
Spectra-622 (PM5313) Driver Manual Data Structures
Field Name
tocLos tocLof tocLais tocLrdi tocOof tocRdool tocTrool sopOof sopLof sopLos sopBipe sstbRtim sstbRtiu lopSf lopSd lopLrdi lopLais lopBipe lopLrei lopSdber lopSfber lopZ1S1 lopCoaps lopPsbf rppsTim[4][3] rppsTiu[4][3] rppsLom1[4][3] rppsLop1[4][3]
Field Type
UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1
Field Description
Loss of signal (LOS) Loss of frame (LOF) Line alarm indication signal (LAIS) Line remote defect indication (LRDI) Out of frame (OOF) Receive data out of lock (RDOOL) Transmit reference out of lock (TROOL) Out of frame Loss of frame Loss of signal Bip-8 (B1) error Receive section trace identifier (Mode1) mismatch Receive section trace identifier (Mode 1) unstable Signal fail (SF) Signal degrade (SD) Line remote defect indication Line alarm indication signal Bip-8 (B2) error Line remote error indication Signal degrade threshold Signal fail threshold Change in the received synchronization status Change in the receive APS code Protection switch byte failure Path trace identifier (Mode 1) mismatch Path trace identifier (Mode 1) unstable Loss of multiframe Loss of pointer
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
38
Spectra-622 (PM5313) Driver Manual Data Structures
Field Name
rppsPslm[4][3] rppsPslu[4][3] rppsPais1[4][3] rppsPrdi1[4][3] rppsPerdi[4][3] rppsTiu2[4][3] rppsPaisCon[4][3] rppsLopCon[4][3] rppsNewPtr[4][3] rppsPrei[4][3] rppsBipe[4][3] rppsPrdi2[4][3] rppsPais2[4][3] rppsAu3PaisCon[4][3] rppsLop2[4][3] rppsAu3LopCon[4][3] rppsErdi[4][3] rppsNdf[4][3] rppsPse[4][3] rppsNse[4][3] rppsInvNdf[4][3] rppsDiscopa[4][3] rppsIllreq[4][3] rppsComa[4][3] rppsLom2[4][3] rppsDpje[4][3] rppsEse[4][3] rppsIsf[4][3] rppsRtim[4][3]
Field Type
UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1
Field Description
Path signal label mismatch Path signal label unstable Path alarm indication signal Path remote defect indication Path enhanced remote defect indication Path trace identifier mode 2 unstable Path alarm indication signal concatenation Loss of pointer concatenation Reception of new_point Path remote error indication Bip-8 error Path remote defect indication Path alarm indication signal AU3 concatenation path AIS Loss of pointer AU3 concatenation Loss of pointer Path enhanced remote defect indication Detection of an NDF_enable Positive pointer adjustment event Negative pointer adjustment event Invalid NDF code Change of pointer alignment event Illegal pointer justification request Change of multiframe alignment Loss of multiframe DROP bus pointer justification event Elastic store error Incoming signal failure Receive path trace identifier (Mode 1) mismatch
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
39
Spectra-622 (PM5313) Driver Manual Data Structures
Field Name
rppsRtiu[4][3] rppsRpslm[4][3] rppsRpslu[4][3] rppsUfl[4][3] rppsOfl[4][3] tppsLom1[4][3] tppsLop1[4][3] tppsPais1[4][3] tppsPaisCon[4][3] tppsLopCon[4][3] tppsPje[4][3] tppsEse[4][3] tppsIsf[4][3] tppsNewPtr[4][3] tppsPrei[4][3] tppsBipe[4][3] tppsPais2[4][3] tppsAu3PaisCon[4][3] tppsLop2[4][3] tppsAu3LopCon[4][3] tppsNdf[4][3] tppsPse[4][3] tppsNse[4][3] tppsInvNdf[4][3] tppsDiscopa[4][3] tppsIllreq[4][3] tppsComa[4][3] tppsLom2[4][3]
Field Type
UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1
Field Description
Receive path trace identifier (Mode 1) unstable Receive path signal label mismatch Receive path signal label unstable Elastic store underflow Elastic store overflow Loss of multiframe Loss of pointer Path alarm indication signal Path alarm indication signal concatenation Loss of pointer concatenation Pointer justification event Elastic store error Incoming signal failure Reception of a new_point indication Path remote error indication Bip-8 error Path alarm indication signal AU3 concatenation path alarm indication signal Loss of pointer AU3 concatenation loss of pointer Detection of an NDF_enable indication Positive pointer adjustment event Negative pointer adjustment event Invalid NDF code Change of pointer alignment event Illegal pointer justification request Change of multiframe alignment Loss of multiframe
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
40
Spectra-622 (PM5313) Driver Manual Data Structures
Field Name
tppsUfl[4][3] tppsOfl[4][3] wansInt dpgmGenSig[4][3] dpgmMonSig[4][3] dpgmMonErr[4][3] dpgmMonSync[4][3] apgmGenSig[4][3] apgmMonSig[4][3] apgmMonErr[4][3] apgmMonSync[4][3]
Field Type
UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1
Field Description
Elastic store underflow Elastic store overflow Beginning of a phase averaging period DROP generator signal DROP monitor signal DROP monitor byte error DROP monitor synchronize ADD generator signal ADD monitor signal ADD monitor byte error ADD monitor synchronize
4.3
Structures in the Driver's Allocated Memory
These structures are defined and used by the driver and are part of the context memory allocated when the driver is opened.
Module Data Block: MDB
The MDB is the top-level structure for the Module. It contains configuration data about the Module level code and pointers to configuration data about the Device level codes. Table 13: Module Data Block: sSPE_MDB
Field Name
errModule valid maxDevs numDevs maxInitProfs maxDiagProfs
Field Type
INT4 UINT2 UINT2 UINT2 UINT2 UINT2
Field Description
Global error Indicator for module calls Indicates that this structure has been initialized Maximum number of devices supported Number of devices currently registered Maximum number of initialization profiles Maximum number of diagnostic profiles
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
41
Spectra-622 (PM5313) Driver Manual Data Structures
Field Name
stateModule
Field Type
SPE_MOD_STATE
Field Description
Module state; can be one of the following: SPE_MOD_START, SPE_MOD_IDLE or
SPE_MOD_READY
pddb pinitProfs pdiagProfs
sSPE_DDB * sSPE_INIT_PROF * sSPE_DIAG_PROF *
(array of) Device Data Blocks (DDB) in context memory (array of) initialization profiles (array of) diagnostic profiles
Device Data Block: DDB
The DDB is the top-level structure for each Device. It contains configuration data about the Device level code and pointers to configuration data about Device level sub-blocks. Table 14: Device Data Block: sSPE_DDB
Field Name
errDevice valid baseAddr usrCtxt
Field Type
INT4 UINT2 UINT1* sSPE_USR_CTXT
Field Description
Global error indicator for device calls Indicates that this structure has been initialized Base address of the Device Stores the user's context for the device. It is passed as an input parameter when the driver invokes an application callback Profile number used at initialization Device State; can be one of the following: SPE_START,
SPE_PRESENT, SPE_INACTIVE or SPE_ACTIVE
profileNum stateDevice
UINT2 SPE_DEV_STATE
cfgIO cfgTOC
sSPE_CFG_IO sSPE_CFG_TOC
Input / Output (IO) configuration block Receive / Transmit Transport Overhead Controller (TOC) configuration block
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
42
Spectra-622 (PM5313) Driver Manual Data Structures
Field Name
cfgSOP
Field Type
sSPE_CFG_SOP
Field Description
Receive / Transmit Section Overhead Processor (RSOP/TSOP) configuration block Sonet/SDH Section Trace Buffer (SSTB) configuration block Receive / Transmit Line Overhead Processor (RLOP/TLOP) configuration block Receive Path Processing Slice (RPPS) configuration block Transmit Path Processing Slice (TPPS) configuration block Ring Control Port (RING) configuration block WAN Synchronization controller (WANS) configuration block DROP Bus PRBS Generator and Monitor (DPGM) configuration block ADD Bus PRBS Generator and Monitor (APGM) configuration block Counter configuration structure Indicates the current type of ISR / polling Address for the callback function for IO Events Address for the callback function for TOC Events Address for the callback function for SOP Events Address for the callback function for SSTB Events Address for the callback function for LOP Events Address for the callback function for RPPS Events
cfgSSTB cfgLOP
sSPE_CFG_SSTB sSPE_CFG_LOP
cfgRPPS[4][3] cfgTPPS[4][3] cfgRING cfgWANS cfgDPGM[4][3]
sSPE_CFG_RPPS sSPE_CFG_TPPS sSPE_CFG_RING sSPE_CFG_WANS sSPE_CFG_DPGM
cfgAPGM[4][3]
sSPE_CFG_APGM
cfgCnt pollISR cbackIO cbackTOC cbackSOP cbackSSTB cbackLOP cbackRPPS
sSPE_CFG_CNT SPE_POLL sSPE_CBACK sSPE_CBACK sSPE_CBACK sSPE_CBACK sSPE_CBACK sSPE_CBACK
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
43
Spectra-622 (PM5313) Driver Manual Data Structures
Field Name
cbackTPPS cbackWANS cbackDPGM cbackAPGM
Field Type
sSPE_CBACK sSPE_CBACK sSPE_CBACK sSPE_CBACK
Field Description
Address for the callback function for TPPS Events Address for the callback function for WANS Events Address for the callback function for DPGM Events Address for the callback function for APGM Events Interrupt Enable Mask
mask
sSPE_MASK
Input / Output (IO) Status Table 15: Input/Output Status: sSPE_STATUS_IO
Field Name
refclkActive rool
Field Type
UINT1 UINT1
Field Description
Monitors for low to high transitions on the REFCLK reference clock input. Monitors the transmit reference out of lock status to report if the synthesis phase lock loop is unable to lock to the reference clock on REFLCK. Monitors for low to high transitions on the DCK input. Monitors for low to high transitions on the ACK input. Reports the value of the SENDLRDI bit position in the transmit ring control port. Reports the value of the SENDLAIS bit position in the transmit ring control port. The loss of transition status indicates the receive power is lost or at least 95 consecutive ones or zeros have been received.
dckAct ackActiv insLRDI insLAIS rlos
UINT1 UINT1 UINT1 UINT1 UINT1
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
44
Spectra-622 (PM5313) Driver Manual Data Structures
Field Name
rrool
Field Type
UINT1
Field Description
Monitors the recovered reference out of lock status to report if the clock recovery phase locked loop is unable to lock to the reference clock on REFCLK. Monitors the recovered data out of lock status to report if the clock recovery phase locked loop is unable to recover and lock to the input data stream. Monitors for low to high transitions on the sampled DS3TDAT input for the TPPS. Monitors for low to high transitions on the DS3TICLK input for the TPPS. Monitors for low to high transitions on the corresponding APL[n], AC1J1V1[n] and ADP[n] inputs.addControlActiv[n] is non-zero when rising edges have been observed on all these signals. Monitors for low to high transitions on the corresponding AD[7:0] (#1), AD[15:8] (#2), AD[23:16] (#3) or AD[31:24] (#4) bus when configured for byte Telecom ADD bus mode. addDataActiv[n] is nonzero when rising edges have been observed on all the required signals in the corresponding Telecom ADD bus. Status of the associated SCPI[3:0] input pins.
rdool
UINT1
ds3tdatAct ds3tiClkAct addControlAct[4]
UINT1 UINT1 UINT1
addDataAct[4]
UINT1
scpi[4]
UINT1
Section Overhead Processor (SOP) Status Table 14: Section Overhead Processor Status: sSPE_STATUS_SOP
Field Name
los
Field Type
UINT1
Field Description
The LOSV bit is set high when loss of signal is declared. LOS is removed when two valid framing words (A1, A2) are detected, and during the intervening time (125 s), no violating period of all zeros patterns is observed.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
45
Spectra-622 (PM5313) Driver Manual Data Structures
Field Name
lof
Field Type
UINT1
Field Description
The LOFV bit is set high when loss of frame is declared. LOFV is set high and loss of frame declared when an out-of-frame state persists for 3 ms. LOF is removed when an in frame state persists for 3 ms. The OOFV bit is set high when out of frame is declared. OOFV is set high and out-of frame declared while the SPECTRA-622 is unable to find a valid framing pattern (A1, A2) in the incoming stream. OOF is removed when a valid framing pattern is detected. Monitors the receive section trace identifier unstable status, which is dependent on the Trace Identifier Mode. In Mode 1, the bit is set high when 8 trace messages mismatching against their immediate predecessor message have been received without a persistent message being detected. In Mode 2, RTIUV is set low during the stable state which is declared after having received the same 16 byte trace message 3 consecutive times. Monitors the receive section trace identifier mismatch status to report if the accepted message differs from the expected message.
oof
UINT1
tiu
UINT1
tim
UINT1
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
46
Spectra-622 (PM5313) Driver Manual Data Structures
Line Overhead Processor (LOP) Status Table 15: Line Overhead Status: sSPE_STATUS_LOP
Field Name
sfber sdber psbf lrdi lais
Field Type
UINT1 UINT1 UINT1 UINT1 UINT1
Field Description
Indicate the signal failure threshold crossing alarm state. Indicates the signal degrade threshold crossing alarm state. Indicates the protection switching byte failure alarm state. Indicates when the line Remote Defect Indication (RDI) is detected. Indicates when the line Alarm Indication Signal (AIS) is detected.
Receive Path Processing Slice (RPPS) Status Table 16: Receive Path Status: sSPE_STATUS_RPPS
Field Name
ptiu
Field Type
UINT1
Field Description
Monitors the receive path trace identifier unstable status bit (RTIUV), which is dependent on the Trace Identifier Mode. In Mode 1, the bit is set high when 8 trace messages mismatching against their immediate predecessor message have been received without a persistent message being detected. In Mode 2, RTIUV is set low during the stable state which is declared after having received the same 16 byte trace message 3 consecutive times. Monitors the receive path trace identifier mismatch status bit (RTIMV) in Trace Identifier Mode 1 to report if the accepted message differs from the expected message. Indicates reception of path AIS alarm in the concatenation indication in the receive STS-1 (STM-0/AU3) or equivalent stream.
ptim
UINT1
au3paisc
UINT1
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
47
Spectra-622 (PM5313) Driver Manual Data Structures
Field Name
au3plopc
Field Type
UINT1
Field Description
Indicates entry to LOPCON_state for the receive STS-1 (STM-0/AU3) or equivalent stream in the RPOP pointer interpreter. Indicates reception of path AIS alarm in the receive stream. Indicates entry to the LOP_state in the RPOP pointer interpreter state machine. Indicates reception of path RDI alarm in the receive stream. Reflect the current filtered value of the enhanced RDI codepoint (G1 bits 5, 6, & 7) for the receive SONET/SDH stream. Filtering is controlled using rdi10 in the RPPS configuration block. Reports the current state of the multiframe framer monitoring the receive stream. Reports an incoming signal fail alarm. Monitors the unequipped status bit (UNEQV), which is dependent on the PSL Mode. In Mode 1, this bit is set high when the accepted path signal label indicates that the path connection is unequipped. When in PSL Mode 2, the UNEQV is set high upon the reception of five consecutive frames with an unequipped (00h) label. Monitors the receive path signal label mismatch status bit (RPSLMV), which is dependent on the PSL Mode. In Mode 1, this bit reports the match/mismatch status between the expected and the accepted path signal label. In Mode 2, this bit reports the match/mismatch status between the expected and the received path signal label. Monitors the receive path signal label unstable status bit (RPSLUV) and is independent on the PSL Mode. This bit reports the stable/unstable status of the path signal label in the receive stream.
pais lop prdi erdiv
UINT1 UINT1 UINT1 UINT1
lom isf uneq
UINT1 UINT1 UINT1
pslm
UINT1
pslu
UINT1
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
48
Spectra-622 (PM5313) Driver Manual Data Structures
Field Name
dropGenSig
Field Type
UINT1
Field Description
Indicates if the partial pseudo random sequence (PRBS) begin generated is correctly aligned with the partial PRBS begin generated in the master generator. Indicates if the partial pseudo random sequence (PRBS) being monitored for is correctly aligned with the partial PRBS being monitored for by the master generator. Reports when the monitor is out of synchronization
dropMonSig
UINT1
dropMonSync
UINT1
Transmit Path Processing Slice (TPPS) Status Table17: Transmit Path Status: sSPE_STATUS_TPPS
Field Name
isf au3lopc
Field Type
UINT1 UINT1
Field Description
Reports an incoming signal failure detected. Indicates entry to LOPCON_state for the transmit STS-1 (STM-0/AU3) or equivalent stream in the TPIP pointer interpreter. Indicates reception of path AIS alarm in the concatenation indication in the transmit STS-1 (STM-0/AU3) or equivalent stream. Indicates entry to the LOP_state in the TPIP pointer interpreter state machine. Indicates reception of path AIS alarm in the receive stream. Indicates remote defect indication detected in transmit stream. Reports the current state of the multiframe framer monitoring the receive stream. Indicates if the partial pseudo random sequence (PRBS) begin generated is correctly aligned with the partial PRBS begin generated in the master generator.
au3paisc
UINT1
lop pais rdi lom addGenSig
UINT1 UINT UINT1 UINT1 UINT1
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
49
Spectra-622 (PM5313) Driver Manual Data Structures
Field Name
addMonSig
Field Type
UINT1
Field Description
Indicates if the partial pseudo random sequence (PRBS) being monitored for is correctly aligned with the partial PRBS being monitored for by the master generator Reports when the monitor is out of synchronization Reports when the monitor is out of synchronization
addMonSync addMonSync
UINT1 UINT1
Statistic Counter Configuration (CFG_CNT)
This structure contains all the fields needed to configure the device counters. It is also passed via the spectraCfgStats function call. Table 16: Counters Config: sSPE_CFG_CNT
Field Name
sopBlkBip
Field Type
UINT1
Field Description
Enables the accumulating of section block BIP errors. When non-zero, one or more errors in the section BIP-8 byte (B1) results in a single error accumulated in the B1 error counter. When zero, all errors in the B1 byte are accumulated in the B1 error counter.
lopBlkRei
UINT1
Controls the accumulation of REI's. When non-zero, and the REI has a value between 1 and 4, the REI event counter is incremented for each set REI bit. If the REI has value greater than 4, and is valid, the REI counter is only incremented by 4. When zero, the REI event counter is incremented for each and every REI bit that occurs during that frame. The counter may be incremented up to 96 times. The REI counter is not incremented for invalid REI codewords.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
50
Spectra-622 (PM5313) Driver Manual Data Structures
Field Name
lopBlkBip
Field Type
UINT1
Field Description
Controls the accumulation of B2 errors. When non-zero, the B2 error event counter is incremented only once per frame whenever one or more B2 bit errors occur during that frame. When zero, the B2 error event counter is incremented for each B2 bit error that occurs during that frame (the counter can be incremented up to 96 times per frame).
rppsMonrs[4][3]
UINT1
When non-zero, selects the receive side pointer justification events counters to monitor the receive stream directly. When zero, the counters accumulates pointer justification events on the DROP bus.
rppsBlkBip[4][3]
UINT1
When non-zero, indicates that path BIP-8 errors are to be reported and accumulated on a block basis. A single BIP error is accumulated and reported to the return transmit path overhead processor if any of the BIP-8 results indicates a mismatch. When zero, BIP-8 errors are accumulated on a bit basis.
rppsBlkRei[4][3]
UINT1
When non-zero, block REI indicates that path REI counts are to be reported and accumulated on a block basis. A single REI error is accumulated if the received REI code is between 1 and 8 inclusive. When zero, REI errors are accumulated literally.
Statistic Counters (CNT)
This structure, as well as its component structures, is being used by the statistics collection APIs to retrieve the device counts. The user can either collect all statistics at once by using spectraGetCnt, or collect statistics from individual blocks using
spectraGetCntSOP, spectraGetCntLOP, spectraGetCntRPPS, spectraGetCntTPPS, and/or spectraGetCntPJ.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
51
Spectra-622 (PM5313) Driver Manual Data Structures
Table 17: Statistic Counters: sSPE_STAT_CNT
Field Name
cntSOP cntLOP cntRPPS[4][3] cntTPPS[4][3] cntPJ[4][3]
Field Type
sSPE_STAT_CNT_SOP sSPE_STAT_CNT_LOP sSPE_STAT_CNT_RPPS sSPE_STAT_CNT_TPPS sSPE_STAT_CNT_PJ
Field Description
Statistics counters of the Section Overhead (SOH) Statistics counters of the Line Overhead (LOH) Statistics counters of the Receive Path Overhead (RPOH) Statistics counters of the Transmit Path Overhead (TPOH) Statistics counters of the Pointer Justifications
Section Overhead (SOP) Statistics Counters Table 18: Section Overhead Statistics Counters: sSPE_STAT_CNT_SOP
Field Name
sopBip
Field Type
UINT4
Field Description
Section BIP errors counter
Line Overhead (LOP) Statistics Counters Table 19: Line Overhead Statistic Counters: sSPE_STAT_CNT_LOP
Field Name
lopBip lopRei
Field Type
UINT4 UINT4
Field Description
Line BIP errors counter Line REI error counter
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
52
Spectra-622 (PM5313) Driver Manual Data Structures
Receive Path Overhead (RPOH) Statistics Counters Table 20: SPECTRA-622 Receive Path Processing Statistics Counters: sSPE_STAT_CNT_RPPS
Field Name
rppsBip rppsRei rppsDPGMPrse
Field Type
UINT4 UINT4 UINT4
Field Description
Path BIP error counter Path REI error counter Number of PRBS byte errors detected since the last accumulation interval. Errors are only accumulated in the synchronized state and each PRBS data byte can have a maximum of 1 errors.
Transmit Path Overhead (TPOH) Statistics Counters Table 21: Transmit Path Processing Statistics Counters: STAT_CNT_TPPS
Field Name
tppsAPGMPrse
Field Type
UINT4
Field Description
Number of PRBS byte errors detected since the last accumulation interval. Errors are only accumulated in the synchronized state and each PRBS data byte can have a maximum of 1 errors.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
53
Spectra-622 (PM5313) Driver Manual Data Structures
Pointer Justification Statistics Counters Table 22: Pointer Justification Statistics Counters: STAT_CNT_PJ
Field Name
rppsPosJust
Field Type
UINT4
Field Description
Positive RPPS pointer justification event counter Negative RPPS pointer justification event counter Positive TPPS pointer justification event counter Negative TPPS pointer justification event counter
rppsNegJust tppsPosJust tppsNegJust
UINT4 UINT4 UINT4
4.4
Structures Passed Through RTOS Buffers
Interrupt Service Vector: ISV
This block is used in two ways. First it is used to determine the size of buffer required by the RTOS for use in the driver. Second it is the template for data that is captured during ISR processing and sent to the Deferred Processing Routine (DPR). Table 23: Interrupt Service Vector: sSPE_ISV
Field Name
deviceHandle mask
Field Type
sSPE_HNDL sSPE_MASK
Field Description
Handle to the device in cause
sSPE_MASK
Deferred Processing Vector: DPV
This block is used in two ways. First it is used to determine the size of buffer required by the RTOS for use in the driver. Second it is the template for data that is assembled by the DPR and sent to the application code. Note: the application code is responsible for returning this buffer to the RTOS buffer pool.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
54
Spectra-622 (PM5313) Driver Manual Data Structures
Table 24: Deferred Processing Vector: sSPE_DPV
Field Name
event cause
Field Type
SPE_DPR_EVENT UINT2
Field Description
Event being reported Reason for the Event
4.5
Global Variable
Most variables within the driver are not meant to be used by the application code. There is one, however, that can be of great use to the application code:
spectraMdb: A global pointer to the Module Data Block (MDB). This global variable is to be considered read only by the application.
*
errModule: This structure element is used to store an error code that specifies the
reason for an API function's failure. The field is only valid when the function in question returns a SPE_FAILURE value. * *
stateModule: This structure element is used to store the Module state. pddb[ ]: An array of pointers to the individual Device Data Blocks. The USER is
cautioned that a DDB is only valid if the `valid' flag is set. Note that the DDBs are in no particular order.
errDevice: This structure element is used to store an error code that specifies
the reason for an API function's failure. The field is only valid when the function in question returns a SPE_FAILURE value.
stateDevice: This structure element is used to store the Device state.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
55
Spectra-622 (PM5313) Driver Manual Application Programming Interface
5
APPLICATION PROGRAMMING INTERFACE
This section provides a detailed description of each function that is a member of the SPECTRA-622 driver Application Programming Interface (API).
5.1
Module Initialization
Opening the Driver Module: spectraModuleOpen
This function performs module level initialization of the device driver. This involves allocating all of the memory needed by the driver and initializing the Module Data Block (MDB) with the passed Module Initialization Vector (MIV). Prototypes Inputs
INT4 spectraModuleOpen(sSPE_MIV *pmiv, sSPE_MDB** ppmdb) pmiv ppmdb ppmdb
: (pointer to) Module Initialization Vector : (pointer to) pointer to the Module Data Block : pointer to the Module Data Block
Outputs Returns
Success = SPE_SUCCESS Failure = START Changes MODULE state to IDLE
Valid States Side Effects
Closing the Driver Module: spectraModuleClose
This function performs module level shutdown of the driver. This involves deleting all devices being controlled by the driver (by calling spectraDelete for each device) and de-allocating the MDB. Prototype Inputs
INT4 spectraModuleClose(void)
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
56
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Outputs Returns
None Success = SPE_SUCCESS Failure = ALL STATES Changes MODULE state to START
Valid States Side Effects
5.2
Module Activation
Starting the Driver Module: spectraModuleStart
This function performs module level startup of the driver. This involves allocating semaphores and timers, initializing buffers and installing the ISR handler and DPR task. Upon successful return of this function the driver is ready to add devices. Prototype Inputs Outputs Returns
INT4 spectraModuleStart(void)
None None Success = SPE_SUCCESS Failure = IDLE Changes MODULE state to READY
Valid States Side Effects
Stopping the Driver Module: spectraModuleStop
This function performs module level shutdown of the driver. This involves deleting all devices being controlled by the driver and removing the ISR handler and DPR task.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
57
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Prototype Inputs Outputs Returns
INT4 spectraModuleStop(void)
None None Success = SPE_SUCCESS Failure = < SPECTRA-622 ERROR CODE> READY Changes MODULE state to IDLE
Valid States Side Effects
5.3
Profile Management
Initialization Profile Creating an Initialization Profile: spectraAddInitProfile
This function creates an initialization profile that is stored by the driver. A device can now be initializaed by simply passing an initialization profile number. Prototype
INT4 spectraAddInitProfile(sSPE_INIT_PROF *pProfile, UINT2 *pProfileNum) pProfile pProfileNum
Inputs
: (pointer to) initialization profile being added : (pointer to) profile number to be assigned by the driver : profile number assigned by the driver
Outputs Returns
pProfileNum
Success = SPE_SUCCESS Failure = IDLE, READY None
Valid States Side Effects
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
58
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Retrieving an Initialization Profile: spectraGetInitProfile
This function retrieves the contents of the initialization profile. Prototype
INT4 spectraGetInitProfile(UINT2 profileNum, sSPE_INIT_PROF *pProfile) profileNum pProfile pProfile
Inputs
: initialization profile number : (pointer to) initialization profile : contents of the corresponding profile
Outputs Returns
Success = SPE_SUCCESS Failure = IDLE, READY None
Valid States Side Effects
Deleting an Initialization Profile: spectraDeleteInitProfile
This function deletes an initialization profile given its profile number. Prototype Inputs Outputs Returns
INT4 spectraDeleteInitProfile(UINT2 profileNum) profileNum
: initialization profile number
None Success = SPE_SUCCESS Failure = IDLE, READY None
Valid States Side Effects
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
59
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Diagnostic Profile Creating a Diagnostic Profile: spectraAddDiagProfile
This function creates a diagnostic profile that is stored by the driver. Passing the diagnostic profile number starts a diagnostic. Prototype
INT4 spectraAddDiagProfile(sSPE_DIAG_PROF *pProfile, UINT2 *pProfileNum) pProfile pProfileNum pProfileNum
Inputs
: (pointer to) diagnostic profile being added : (pointer to) profile number : profile number assigned by the driver
Outputs Returns
Success = SPE_SUCCESS Failure = IDLE, READY None
Valid States Side Effects
Retrieving a Diagnostic Profile: spectraGetDiagProfile
This function retrieves the contents of a diagnostic profile. Prototype
INT4 spectraGetDiagProfile(UINT2 profileNum, sSPE_DIAG_PROF *pProfile) profileNum pProfile pProfile
Inputs
: diagnostic profile number : (pointer to) diagnostic profile : contents of the corresponding profile
Outputs Returns
Success = SPE_SUCCESS Failure =
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
60
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Valid States Side Effects
IDLE, READY None
Deleting a Diagnostic Profile: spectraDeleteDiagProfile
This function deletes a diagnostic profile. Prototype Inputs Outputs Returns
INT4 spectraDeleteDiagProfile(UINT2 profileNum) profileNum
: diagnostic profile number
None Success = SPE_SUCCESS Failure = IDLE, READY None
Valid States Side Effects
5.4
Device Addition and Deletion
Adding a Device: spectraAdd
Verifies the presence of a new device in the hardware then returns a handle back to the user. The device handle is passed as a parameter of most of the Device API Functions. It is used by the driver to identify the device on which the operation is to be performed. Prototype
sSPE_HNDL spectraAdd(void *usrCtxt, UINT1 *baseAddr, INT4 **pperrDevice) usrCtxt baseAddr pperrDevice
Inputs
: user context for this device : base address of the device : (pointer to) an area of memory
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
61
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Outputs Returns
pperrDevice
: (pointer to) errDevice (inside the DDB)
Device handle (to be used as an argument to most of the SPECTRA-622 APIs) or NULL pointer in case of an error READY Changes the DEVICE state to PRESENT
Valid States Side Effects
Deleting a Device: spectraDelete
This function is used to remove the specified device from the list of devices being controlled by the SPECTRA-622 driver. Deleting a device involves clearing the DDB for that device and releasing its associated device handle. Prototype Inputs Outputs Returns
INT4 spectraDelete(sSPE_HNDL deviceHandle) deviceHandle
: device Handle (from spectraAdd)
None Success = SPE_SUCCESS Failure = PRESENT, ACTIVE, INACTIVE None
Valid States Side Effects
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
62
Spectra-622 (PM5313) Driver Manual Application Programming Interface
5.5
Device Initialization
Initializing a Device: spectraInit
This function initializes the Device Data Block (DDB) that is associated with that device during spectraAdd. It applies a reset to the device and configures it according to the DIV passed by the Application. If the DIV is passed as a NULL the profile number is used. A profile number of zero indicates that all the register bits are to be left in their default state (after a soft reset). Note that the profile number is ignored UNLESS the passed DIV is NULL. Prototype
INT4 spectraInit(sSPE_HNDL deviceHandle, sSPE_DIV *pdiv, UINT2 profileNum) deviceHandle pdiv profileNum
Inputs
: device Handle (from spectraAdd) : (pointer to) Device Initialization Vector : profile number (ignored if pdiv is NULL)
Outputs Returns
None Success = SPE_SUCCESS Failure = PRESENT Changes DEVICE state to INACTIVE
Valid States Side Effects
Updating the Configuration of a Device: spectraUpdate
Updates the configuration of the device as well as the Device Data Block (DDB) associated with that device according to the DIV passed by the Application. The only difference between spectraUpdate and spectraInit is that no soft reset will be applied to the device. Prototype
INT4 spectraInit(sSPE_HNDL deviceHandle, sSPE_DIV *pdiv, UINT2 profileNum) deviceHandle pdiv profileNum
Inputs
: device Handle (from spectraAdd) : (pointer to) Device Initialization Vector : profile number (ignored if pdiv is NULL)
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
63
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Outputs Returns
None Success = SPE_SUCCESS Failure = PRESENT Changes DEVICE state to INACTIVE
Valid States Side Effects
Resetting a Device: spectraReset
This function applies a software reset to the SPECTRA-622 device. It also resets all the DDB contents (except for the user context). This function is typically called before reinitializing the device. Prototype Inputs Outputs Returns Valid States Side Effects
void spectraReset(sSPE_HNDL deviceHandle) deviceHandle
: device Handle (from spectraAdd)
None None ACTIVE, INACTIVE Changes DEVICE state to PRESENT
5.6
Device Activation and De-Activation
Activating a Device: spectraActivate
This function restores the state of a device after it has been deactivated. Interrupts may be re-enabled after deactivation.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
64
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Prototype Inputs Outputs Returns
INT4 spectraActivate(sSPE_HNDL deviceHandle) deviceHandle
: device Handle (from spectraAdd)
None Success = SPE_SUCCESS Failure = Inactive Change the DEVICE state to ACTIVE
Valid States Side Effects
DeActivating a Device: spectraDeActivate
This function de-activates the device from operation. In the process, interrupts are masked and the device is put into a quiet state via enable bits. Prototype Inputs Outputs Returns
INT4 spectraDeActivate(sSPE_HNDL deviceHandle) deviceHandle
: device Handle (from spectraAdd)
None Success = SPE_SUCCESS Failure = ACTIVE Changes the DEVICE state to INACTIVE
Valid States Side Effects
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
65
Spectra-622 (PM5313) Driver Manual Application Programming Interface
5.7
Device Reading and Writing
Reading from a Device Register: spectraRead
This function can be used to read a register of a specific SPECTRA-622 device by providing the register number. This function derives the actual address location based on the device handle and register number inputs. It then reads the contents of this address location using the system specific macro, sysSpectraRead. Note: A failure to read returns a zero and any error indication is written to the DDB. Prototype Inputs
UINT1 spectraRead(sSPE_HNDL deviceHandle, UINT2 regNum) deviceHandle regNum
: device Handle (from spectraAdd) : register number
Outputs Returns
ERROR code written to the DDB Success = the register value Failure = 0x00 ALL DEVICE STATES May affect registers that change after a read operation
Valid States Side Effects
Writing to a Device: spectraWrite
This function can be used to write to a register of a specific SPECTRA-622 device by providing the register number. The function derives the actual address location based on the device handle and register number inputs. It then writes the contents of this address location using the system specific macro sysSpectraWrite. Note: A failure to write returns a zero and any error indication is written to the DDB. Prototype Inputs
UINT1 spectraWrite(sSPE_HNDL deviceHandle, UINT2 regNum, UINT1 value) deviceHandle regNum value
: device Handle (from spectraAdd) : register number : value to be written
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
66
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Outputs Returns
ERROR code written to the DDB Success = previous value Failure = 0x00 ALL DEVICE STATES May change the configuration of the Device
Valid States Side Effects
Reading a Block of Registers: spectraReadBlock
This function can be used to read a register block of a specific SPECTRA-622 device by providing the starting register number, and the size to read. The function derives the actual start address location based on the device handle and starting register number inputs. It then reads the contents of this data block using multiple calls to the system specific macro and sysSpectraRead. Note: Any error indication is written to the DDB. It is the USER's responsibility to allocate enough memory for the block read. Prototype
void spectraReadBlock(sSPE_HNDL deviceHandle, UINT2 startRegNum, UINT2 size, UINT1 *pblock) deviceHandle startRegNum size pblock
Inputs
: device Handle (from spectraAdd) : starting register number : size of the block to read : (pointer to) the block to read
Outputs
ERROR code written to the DDB pblock : (pointer to) the block read None ALL DEVICE STATES May affect registers that change after a read operation
Returns Valid States Side Effects
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
67
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Writing a Block of Registers: spectraWriteBlock
This function can be used to write to a register block of a specific SPECTRA-622 device by providing the starting register number and the block size. The function derives the actual starting address location based on the device handle and starting register number inputs. It then writes the contents of this data block using multiple calls to the system specific macro and sysSpectraWrite. A bit from the passed block is only modified in the device's registers if the corresponding bit is set in the passed mask. Note: Any error indication is written to the DDB Prototype
void spectraWriteBlock(sSPE_HNDL deviceHandle, UINT2 startRegNum, UINT2 size, UINT1 *pblock, UINT1 *pmask) deviceHandle startRegNum size pblock pmask
Inputs
: device Handle (from spectraAdd) : starting register number : size of block to read : (pointer to) block to write : (pointer to) mask
Outputs Returns Valid States Side Effects
ERROR code written to the DDB None ALL DEVICE STATES May change the configuration of the Device
5.8
Transport Overhead Controller (TOC)
Modifying the Z0 Byte: spectraTOCWriteZ0
This function writes the Z0 byte into the transmit transport overhead. Prototype Inputs
INT4 spectraTOCWriteZ0(sSPE_HNDL deviceHandle, UINT1 Z0) deviceHandle Z0
: device Handle (from spectraAdd) : Z0 byte to write
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
68
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Modifying the S1 Byte: spectraTOCWriteS1
This function writes the S1 byte into the transmit transport overhead. Prototype Inputs
INT4 spectraTOCWriteS1(sSPE_HNDL deviceHandle, UINT1 S1) deviceHandle S1
: device Handle (from spectraAdd) : S1 byte to write
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Reading the S1 Byte: spectraTOCReadS1
This function reads the S1 byte received in the transport overhead of the received stream. Prototype
INT4 spectraTOCReadS1(sSPE_HNDL deviceHandle, UINT1 *pS1)
Inputs
deviceHandle pS1
: device Handle (from spectraAdd) : (pointer to) S1 byte
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
69
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Outputs Returns
pS1
: S1 byte read
Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
5.9
Receive / Transmit Section Overhead Processor (RSOP/TSOP)
Forcing Out-of-Frame: spectraSOPForceOOF
When the enable flag is set, this function forces the Receive section overhead processor out-of-frame. When the enable flag is not set, the function resumes normal processing. Prototype Inputs
INT4 spectraSOPForceOOF(sSPE_HNDL deviceHandle, UINT2 enable) deviceHandle enable
: device Handle (from spectraAdd) : flag to start/stop forcing OOF
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
70
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Inserting Line AIS: spectraSOPInsertLineAIS
When the enable flag is set, this function forces a Line-AIS insertion. When the enable flag is not set, the function resumes normal processing. Prototype Inputs
INT4 spectraSOPInsertLineAIS(sSPE_HNDL deviceHandle, UINT2 enable) deviceHandle enable
: device Handle (from spectraAdd) : flag to start/stop Line-AIS insertion
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Forcing Errors in the A1 Byte: spectraSOPDiagFB
This function enables the insertion of a single bit error continuously in the most significant bit (bit 1) of the A1 section overhead framing byte. A1 bytes are set to 76H instead of F6H. Prototype Inputs
INT4 spectraSOPDiagFB(sSPE_HNDL deviceHandle, UINT2 enable) deviceHandle enable
: device Handle (from spectraAdd) : flag to start/stop error insertion
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
71
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Forcing Errors in the B1 Byte: spectraSOPDiagB1
This function enables insertion of bit errors continuously in the B1 section overhead byte. The B1 byte value is inverted. Prototype Inputs
INT4 spectraSOPDiagB1(sSPE_HNDL deviceHandle, UINT2 enable) deviceHandle enable
: device Handle (from spectraAdd) : flag to start/stop error insertion
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Forcing Loss-Of-Signal: spectraSOPDiagLOS
This function enables the insertion of zeros in the transmit outgoing stream. Prototype Inputs
INT4 spectraSOPDiagLOS(sSPE_HNDL deviceHandle, UINT2 enable) deviceHandle enable
: device Handle (from spectraAdd) : flag to start/stop error insertion
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
72
Spectra-622 (PM5313) Driver Manual Application Programming Interface
5.10 SONET / SDH Section Trace Buffer (SSTB)
Retrieving and Setting the Section Trace Messages: spectraSectionTraceMsg
This function retrieves and sets the section trace message (J0) in the Sonet/SDH Section Trace Buffer. Note: It is the USER's responsibility to ensure that the message pointer points to an area of memory large enough to hold the returned data. Prototype
INT4 spectraSectionTraceMsg(sSPE_HNDL deviceHandle, UINT2 type, UINT1* pJ0) deviceHandle type
Inputs
pJ0
: device Handle (from spectraAdd) : type of access 0 = write tx section trace 1 = read rx accepted section trace 2 = read rx captured section trace 3 = write rx expected section trace : (pointer to) the section trace message
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
5.11 Receive / Transmit Line Overhead Processor (RLOP/TLOP)
Inserting Line Remote Defect Indication: spectraLOPInsertLineRDI
This function enables the insertion of a transmit line remote defect indication (RDI). The Line RDI is inserted by transmitting the code 110 in bit positions 6, 7, and 8 of the K2 byte.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
73
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Prototype
INT4 spectraLOPInsertLineRDI(sSPE_HNDL deviceHandle, UINT2 enable) deviceHandle enable
Inputs
: device Handle (from spectraAdd) : flag to start/stop Line RDI insertion
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Forcing Errors in the B2: spectraLOPDiagB2
This function enables the insertion of bit errors continuously in each of the line BIP-8 bytes (B2 bytes). Each bit of every B2 is inverted. Prototype Inputs
INT4 spectraLOPDiagB2(sSPE_HNDL deviceHandle, UINT2 enable) deviceHandle enable
: device Handle (from spectraAdd) : flag to start/stop B2 error insertion
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
74
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Reading the Received K1 and K2 Bytes: spectraLOPReadK1K2
This function reads the K1 and K2 bytes from the received line overhead. Prototype
INT4 spectraLOPReadK1K2(sSPE_HNDL deviceHandle, UINT1 *pK1, UINT1 *pK2) deviceHandle pK1 pK2 pK1 pK2
Inputs
: device Handle (from spectraAdd) : (pointer to) K1 byte : (pointer to) K2 byte : K1 byte read : K2 byte read
Outputs
Returns
Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Writing the Transmitted K1 and K2 Bytes: spectraLOPWriteK1K2
This function writes the K1 and K2 bytes into the transmit line overhead. Prototype
INT4 spectraLOPWriteK1K2(sSPE_HNDL deviceHandle, UINT1 K1, UINT1 K2) deviceHandle K1 K2
Inputs
: device Handle (from spectraAdd) : K1 byte to write : K2 byte to write
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE
Valid States
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
75
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Side Effects
None
5.12 Receive Path Processing Slice (RPPS)
Retrieving and Setting the Path Trace Messages: spectraPathTraceMsg
This function retrieves and sets the current path trace message (J1) in the Sonet/SDH Path Trace Buffer. Note: It is the USER's responsibility to make sure that the message pointer points to an area of memory large enough to hold the returned data. Prototype
INT4 spectraPathTraceMsg(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 type, UINT1* pJ1) deviceHandle stm1 au3 type
Inputs
pJ1
: device Handle (from spectraAdd) : STM-1 index : AU-3 index : type of access 0 = write tx path trace 1 = read rx accepted path trace 2 = read rx captured path trace 3 = write rx expected path trace : (pointer to) the path trace message : updated path trace message
Outputs Returns
pJ1
Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Forcing Loss-Of-Pointer: spectraRPPSDiagLOP
This function forces the downstream pointer processing to enter the Loss of Pointer (LOP) state. It does so by inverting the new data flag (NDF) field of the payload pointer that is inserted in the DROP bus.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
76
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Prototype
INT4 spectraRPPSDiagLOP(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 enable) deviceHandle stm1 au3 enable
Inputs
: device Handle (from spectraAdd) : STM-1 index : AU-3 index : flag to start/stop NDF inversion
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Forcing Errors in the H4 Byte: spectraRPPSDiagH4
This function enables the inversion of the multiframe indicator (H4) byte in the DROP bus. An inversion forces an out-of-multiframe alarm in the downstream circuitry. This can only occur when the SPE (VC) is used to carry virtual tributary (VT) or tributary unit (TU) based payloads. Prototype
INT4 spectraRPPSDiagH4(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 enable) deviceHandle stm1 au3 enable
Inputs
: device Handle (from spectraAdd) : STM-1 index : AU-3 index : flag to start/stop H4 inversion
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE
Valid States
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
77
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Side Effects
None
Forcing Tributary Path AIS: spectraRPPSInsertTUAIS
This function enables the insertion of tributary path AIS on the DROP bus for VT1.5 (TU11), VT2 (TU12), VT3 and VT6 (TU2) payloads. Columns in the DROP bus carrying tributary traffic are set to all ones. The pointer bytes (H1, H2, and H3), the path overhead column, and the fixed stuff columns remain unaffected. Note: This is not applicable for TU3 tributary payloads. Prototype
INT4 spectraRPPSInsertTUAIS(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 enable) deviceHandle stm1 au3 enable
Inputs
: device Handle (from spectraAdd) : STM-1 index : AU-3 index : flag to start/stop TUAIS
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Forcing DS3 AIS: spectraRPPSDs3AisGen
Forces generation of DS3 AIS. Note: Any data on the STS-1 (STM-0/AU3) SPE is then lost. Prototype
INT4 spectraRPPSDs3AisGen(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 enable) deviceHandle stm1 au3
Inputs
: device Handle (from spectraAdd) : STM-1 index : AU-3 index
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
78
Spectra-622 (PM5313) Driver Manual Application Programming Interface
enable
: flag to start/stop DS3 AIS generation
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
5.13 Transmit Path Processing Slice (TPPS)
Forcing Path AIS: spectraTPPSInsertPAIS
This function enables the insertion of the path alarm indication signal (PAIS) in the transmit stream. The synchronous payload envelope and the pointer bytes (H1 - H3) are set to all ones. Prototype
INT4 spectraTPPSInsertPAIS(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 enable) deviceHandle stm1 au3 enable
Inputs
: device Handle (from spectraAdd) : STM-1 index : AU-3 index : flag to start/stop PAIS insertion
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
79
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Forcing Errors in the B3 Byte: spectraTPPSDiagB3
This function enables the inversion of the path BIP-8 byte (B3) in the transmit stream. The B3 byte is inverted causing the insertion of eight path BIP-8 errors per frame. Prototype
INT4 spectraTPPSDiagB3(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 enable) deviceHandle stm1 au3 enable
Inputs
: device Handle (from spectraAdd) : STM-1 index : AU-3 index : flag to start/stop B3 inversion
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Forcing a Pointer Value: spectraTPPSForceTxPtr
This function enables the insertion of the pointer value passed in argument into the H1 and H2 bytes of the transmit stream. As a result, the upstream payload mapping circuitry and a valid SPE can continue functioning and generating normally. Prototype
INT4 spectraTPPSForceTxPtr(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 enable, UINT2 aptr) deviceHandle stm1 au3 enable aptr
Inputs
: device Handle (from spectraAdd) : STM-1 index : AU-3 index : flag to start/stop generation : pointer value to insert in (H1,H2)
Outputs Returns
None Success = SPE_SUCCESS
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
80
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Failure = Valid States Side Effects ACTIVE, INACTIVE None
Writing the New Data Flag Bits: spectraTPPSInsertNDF
This function enables the insertion of the passed new data flag bits (NDF[3:0]) in the NDF bit positions. Prototype
INT4 spectraTPPSInsertNDF(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 enable, UINT1 ndf) deviceHandle stm1 au3 enable ndf
Inputs
: device Handle (from spectraAdd) : STM-1 index : AU-3 index : flag to start/stop NDF insertion : NDF value
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Writing the Path Remote Error Indication Count: spectraTPPSInsertPREI
This function inserts the path remote error indication count passed in argument inside the path status byte. Prototype
INT4 spectraTPPSInsertPREI(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT1 PREI)
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
81
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Inputs
deviceHandle stm1 au3 prei
: device Handle (from spectraAdd) : STM-1 index : AU-3 index : PREI value
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Forcing Errors in the H4 Byte: spectraTPPSDiagH4
This function enables the inversion of the multiframe indicator (H4) byte in the TRANSMIT stream. This forces an out of multiframe alarm in the downstream circuitry when the SPE (VC) is used to carry virtual tributary (VT) or tributary unit (TU) based payloads. Prototype
INT4 spectraTPPSDiagH4(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 enable) deviceHandle stm1 au3 enable
Inputs
: device Handle (from spectraAdd) : STM-1 index : AU-3 index : flag to start/stop H4 inversion
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
82
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Forcing Tributary Path AIS: spectraRPPSInsertTUAIS
This function enables the insertion of tributary path AIS in the transmit stream for VT1.5 (TU11), VT2 (TU12), VT3 and VT6 (TU2) payloads. Columns in the transmit stream carrying tributary traffic are set to all ones. The pointer bytes (H1, H2, and H3); the path overhead column; and the fixed stuff columns are unaffected. Note: This is not applicable for TU3 tributary payloads.
Prototype
INT4 spectraTPPSInsertTUAIS(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 enable) deviceHandle stm1 au3 enable
Inputs
: device Handle (from spectraAdd) : STM-1 index : AU-3 index : flag to start/stop TUAIS insertion
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Forcing DS3 AIS: spectraTPPSDs3AisGen
This function forces the generation of a DS3 AIS. Note: Any data on the STS-1 (STM0/AU3) SPE is then lost. Prototype
INT4 spectraTPPSDs3AisGen(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 enable) deviceHandle stm1 au3 enable
Inputs
: device Handle (from spectraAdd) : STM-1 index : AU-3 index : flag to start/stop DS3 AIS generation
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
83
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Writing the J1 Byte: spectraTPPSWriteJ1
This function writes the J1 byte into the transmit path overhead Prototype
INT4 spectraTPPSWriteJ1(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT1 J1) deviceHandle stm1 au3 J1
Inputs
: device Handle (from spectraAdd) : STM-1 index : AU-3 index : J1 byte to write
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Writing the C2 Byte: spectraTPPSWriteC2
This function writes the C2 byte into the transmit path overhead. Prototype
INT4 spectraTPPSWriteC2(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT1 C2)
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
84
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Inputs
deviceHandle stm1 au3 C2
: device Handle (from spectraAdd) : STM-1 index : AU-3 index : C2 byte to write
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Writing the F2 Byte: spectraTPPSWriteF2
This function writes the F2 byte into the transmit path overhead. Prototype
INT4 spectraTPPSWriteF2(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT1 F2) deviceHandle stm1 au3 F2
Inputs
: device Handle (from spectraAdd) : STM-1 index : AU-3 index : F2 byte to write
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
85
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Writing the Z3 Byte: spectraTPPSWriteZ3
This function writes the Z3 byte into the transmit path overhead. Prototype
INT4 spectraTPPSWriteZ3(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT1 Z3) deviceHandle stm1 au3 Z3
Inputs
: device Handle (from spectraAdd) : STM-1 index : AU-3 index : Z3 byte to write
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Writing the Z4 Byte: spectraTPPSWriteZ4
This function writes the Z4 byte into the transmit path overhead. Prototype
INT4 spectraTPPSWriteZ4(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT1 Z4) deviceHandle stm1 au3 Z4
Inputs
: device Handle (from spectraAdd) : STM-1 index : AU-3 index : Z4 byte to write
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE
Valid States
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
86
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Side Effects
None
Writing the Z5 Byte: spectraTPPSWriteZ5
This function writes the Z5 byte into the transmit path overhead. Prototype
INT4 spectraTPPSWriteZ5(sSPE_HNDL deviceHandle UINT2 stm1, UINT2 au3, UINT1 Z5) deviceHandle stm1 au3 Z5
Inputs
: device Handle(from spectraAdd) : STM-1 index : AU-3 index : Z5 byte to write
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
5.14 Ring Control Ports (RING)
Sending Line AIS Maintenance Signal: spectraRINGLineAISControl
This function forces a mate SPECTRA-622 to send the line AIS maintenance signal. Prototype Inputs
INT4 spectraRINGLineAISControl(sSPE_HNDL deviceHandle, UINT2 enable) deviceHandle enable
: device Handle (from spectraAdd) : flag to start/stop Line-AIS insertion
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
87
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Sending Line RDI Maintenance Signal: spectraRINGLineRDIControl
This function forces a mate SPECTRA-622 to send the line RDI maintenance signal. Prototype Inputs
INT4 spectraRINGLineRDIControl(sSPE_HNDL deviceHandle, UINT2 enable) deviceHandle enable
: device Handle (from spectraAdd) : flag to start/stop Line-RDI insertion
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
5.15 WAN Synchronization Controller (WANS)
Forcing Phase Reacquisitions: spectraWANSForceReac
This function forces a phase reacquisition of the Phase Detector. Prototype Inputs
INT4 spectraWANSForceReac(sSPE_HNDL deviceHandle) deviceHandle
: device Handle (from spectraAdd)
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
88
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
5.16 DROP Bus and ADD Bus PRBS Monitor and Generator (DPGM & APGM)
Configuring Diagnostics: spectraDiagCfg
This function configures the DPGM and APGM for diagnostics in accordance with the profile passed by the Application. Note: The DPGM and APGM are both disabled by default unless this function is called. A profile number of zero indicates a NULL profile. All register bits are left unchanged. Prototype Inputs
INT4 spectraDiagCfg(sSPE_HNDL deviceHandle, UINT2 profileNum) deviceHandle profileNum
: device Handle (from spectraAdd) : profile number
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE May insert a pseudo random byte sequence inside the payload.
Valid States Side Effects
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
89
Spectra-622 (PM5313) Driver Manual Application Programming Interface
5.17 DPGM Functions
Forcing Generation of a New PRBS: spectraDPGMGenRegen
This function reinitializes the generator LFSR and regenerates the pseudo random bit sequence (PRBS) from the known reset state. The LFSR is dependent on the sequence number. This automatically forces all slaves to reset at the same time. Prototype
INT4 spectraDPGMGenRegen(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3) deviceHandle stm1 au3
Inputs
: device Handle (from spectraAdd) : STM-1 index : AU-3 index
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Forcing Bit Errors: spectraDPGMGenForceErr
This function forces bit errors in the inserted pseudo random bit sequence (PRBS). Thereafter, the MSB of the PRBS is inverted, inducing a single bit error. Prototype
INT4 spectraDPGMGenForceErr(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3) deviceHandle stm1 au3
Inputs
: device Handle (from spectraAdd) : STM-1 index : AU-3 index
Outputs Returns
None Success = SPE_SUCCESS
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
90
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Failure = Valid States Side Effects ACTIVE, INACTIVE None
Forcing a Resynchronization: spectraDPGMonResync
This function forces the resynchronization of the monitor to the incoming pseudo random bit sequence (PRBS). The monitor will go out of synchronization and begin resynchronizing the incoming PRBS payload. This will automatically force all slaves to resynchronize at the same time. Prototype
INT4 spectraDPGMMonResync(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3) deviceHandle stm1 au3
Inputs
: device Handle (from spectraAdd) : STM-1 index : AU-3 index
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
91
Spectra-622 (PM5313) Driver Manual Application Programming Interface
5.18 APGM Functions
Forcing Generation of a New PRBS: spectraAPGMGenRegen
This function re-initializes the generator LFSR and begins regenerating the pseudo random bit sequence (PRBS) from the known reset state. The LFSR is dependent on the sequence number. This automatically forces all slave to reset at the same time. Prototype
INT4 spectraAPGMGenRegen(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3) deviceHandle stm1 au3
Inputs
: device Handle (from spectraAdd) : STM-1 index : AU-3 index
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Forcing Bit Errors: spectraAPGMGenForceErr
This function forces bit errors in the inserted pseudo random bit sequence (PRBS). Thereafter, the MSB of the PRBS is inverted, inducing a single bit error. Prototype
INT4 spectraAPGMGenForceErr(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3) deviceHandle stm1
Inputs
au3 Outputs Returns None
: device Handle (from spectraAdd) : STM-1 index : AU-3 index
Success = SPE_SUCCESS
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
92
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Failure = Valid States Side Effects ACTIVE, INACTIVE None
Forcing a Resynchronization: spectraAPGMonResync
This function forces resynchronization of the monitor to the incoming pseudo random bit sequence (PRBS). This process will automatically force all slaves to resynchronize at the same time. Prototype
INT4 spectraAPGMMonResync(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3) deviceHandle stm1 au3
Inputs
: device Handle (from spectraAdd) : STM-1 index : AU-3 index
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
5.19 Interrupt Service Functions
Getting the Interrupt Mask: spectraGetMask
This function returns the contents of the interrupt mask registers of the SPECTRA-622 device.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
93
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Prototype Inputs
INT4 spectraGetMask(sSPE_HNDL deviceHandle, sSPE_MASK *pmask) deviceHandle pmask
: device Handle (from spectraAdd) : (pointer to) mask structure
Outputs Returns
ERROR code written to the DDB Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Setting the Interrupt Mask: spectraSetMask
This function sets the contents of the interrupt mask registers of the SPECTRA-622 device. Prototype Inputs
INT4 spectraSetMask(sSPE_HNDL deviceHandle, sSPE_MASK *pmask) deviceHandle pmask
: device Handle (from spectraAdd) : (pointer to) mask structure
Outputs Returns
ERROR code written to the DDB Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE May change the operation of the ISR / DPR
Valid States Side Effects
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
94
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Clearing the Interrupt Mask: spectraClearMask
This function clears the individual interrupt bits and registers in the SPECTRA-622 device. Any bits that are set in the passed structure are cleared in the associated registers. Prototype Inputs
INT4 spectraClearMask(sSPE_HNDL deviceHandle, sSPE_MASK *pmask) deviceHandle pmask
: device Handle (from spectraAdd) : (pointer to) mask structure
Outputs Returns
ERROR code written to the DDB Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE May change the operation of the ISR / DPR
Valid States Side Effects
Polling Interrupt Status Registers: spectraPoll
Commands the Driver to poll the interrupt registers in the Device. The call will fail unless the device is initialized in polling mode. Prototype Inputs
INT4 spectraPoll(sSPE_HNDL deviceHandle)
deviceHandle
: device Handle (from spectraAdd)
Outputs Returns
None
Success = SPE_SUCCESS Failure =
SPE_ACTIVE
Valid States Side Effects
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
95
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Interrupt Service Routine: spectraISR
This function reads the state of the interrupt registers in the SPECTRA-622 and stores them into an ISV. It performs whatever functions are needed to clear the interrupt. This routine is called by the application code from within sysSpectraISRHandler. Prototype Inputs Outputs Returns Valid States Side Effects
void *spectraISR(sSPE_HNDL deviceHandle) deviceHandle
: device Handle (from spectraAdd)
None (pointer to) ISV buffer (to send to the DPR) or NULL (pointer) ACTIVE None
Deferred Processing Routine: spectraDPR
This function acts on data contained in an ISV. It creates a DPV that invokes application code callbacks (if defined and enabled), and possibly other performing linked actions. This function is called from within the application function sysSpectraDPRTask. Prototype Inputs Outputs Returns Valid States Side Effects
void spectraDPR(sSPE_ISV *pisv) pisv
: (pointer to) ISV buffer
None None ACTIVE None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
96
Spectra-622 (PM5313) Driver Manual Application Programming Interface
5.20 Alarm, Status and Statistics Functions
Configuring Statistical Counts: spectraCfgStats
This function configures all the statistical counts. Prototype
INT4 spectraCfgStats(sSPE_HNDL deviceHandle, sSPE_CFG_CNT cfgCnt)
Inputs
deviceHandle cfgCnt
: device Handle (from spectraAdd) : counters configuration block
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE, INACTIVE None
Valid States Side Effects
Statistics Collection Routine: spectraGetCnt
This function retrieves all the device counts.Note: It is the USER's responsibility to ensure that the structure points to an area of memory large enough to hold a copy of the counter structure. Prototype
INT4 spectraGetCnt(sSPE_HNDL deviceHandle, sSPE_STAT_CNT *pcnt)
Inputs
deviceHandle pcnt
: device Handle (from spectraAdd) : (pointer to) allocated memory
Outputs
pcnt
: current device counts
Returns
Success = SPE_SUCCESS
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
97
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Failure = Valid States Side Effects
ACTIVE, INACTIVE
None
Retrieving Counter for SOP Block: spectraGetCntSOP
This function retrieves the specified device counts block. Note: It is the USER's responsibility to ensure that the structure points to an area of memory large enough to hold a copy of the counter structure. Prototype
INT4 spectraGetCntSOP(sSPE_HNDL deviceHandle, sSPE_STAT_CNT_SOP *pcntSOP)
Inputs
deviceHandle pcntSOP
: device Handle (from spectraAdd) : (pointer to) allocated memory
Outputs
pcntSOP
: current device counts
Returns
Success = SPE_SUCCESS Failure =
ACTIVE, INACTIVE
Valid States Side Effects
None
Retrieving Counter for LOP Block: spectraGetCntLOP
This function retrieves the specified device counts block.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
98
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Note: It is the USER's responsibility to ensure that the structure points to an area of memory large enough to hold a copy of the counter structure. Prototype
INT4 spectraGetCntLOP(SPE_HNDL deviceHandle, sSPE_STAT_CNT_LOP *pcntLOP)
Inputs
deviceHandle pcntLOP
: device Handle (from spectraAdd) : (pointer to) allocated memory
Outputs
pcntLOP
: current device counts
Returns
Success = SPE_SUCCESS Failure =
ACTIVE, INACTIVE
Valid States Side Effects
None
Retrieving Counter for RPPS Block: spectraGetCntRPPS
This function retrieves the specified device counts block. Note: It is the USER's responsibility to ensure that the structure points to an area of memory large enough to hold a copy of the counter structure. Prototype
INT4 spectraGetCntRPPS(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3, sSPE_STAT_CNT_RPPS *pcntRPPS)
Inputs
deviceHandle stm1 au3 pcntRPPS
: device Handle (from spectraAdd) : STM-1 index : AU-3 index : (pointer to) allocated memory
Outputs
pcntRPPS
: current device counts
Returns
Success = SPE_SUCCESS
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
99
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Failure = Valid States Side Effects
ACTIVE, INACTIVE
None
Retrieving Counter for TPPS Block: spectraGetCntTPPS
This function retrieves the specified device counts block. Note: It is the USER's responsibility to ensure that the structure points to an area of memory large enough to hold a copy of the counter structure. Prototype
INT4 spectraGetCntTPPS(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3, sSPE_STAT_CNT_TPPS *pcntTPPS)
Inputs
deviceHandle stm1
au3
pcntTPPS
: device Handle (from spectraAdd) : STM-1 index : AU-3 index : (pointer to) allocated memory
Outputs
pcntTPPS
: current device counts
Returns
Success = SPE_SUCCESS Failure =
ACTIVE, INACTIVE
Valid States Side Effects
None
Retrieving Counter for Pointer Justifications: spectraGetCntPJ
This function retrieves the specified device counts block.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
100
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Note: It is the USER's responsibility to ensure that the structure points to an area of memory large enough to hold a copy of the counter structure. Prototype
INT4 spectraGetCntTPPS(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3, sSPE_STAT_CNT_PJ *pcntPJ)
Inputs
deviceHandle stm1 au3 pcntPJ
: device Handle (from spectraAdd) : STM-1 index : AU-3 index : (pointer to) allocated memory
Outputs
pcntPJ
: current device counts
Returns
Success = SPE_SUCCESS Failure =
ACTIVE, INACTIVE
Valid States Side Effects
None
Retrieving Alarm Status: spectraGetStatus
This function retrieves the current alarm status by reading all the alarm status registers. Note: It is the USER's responsibility to ensure that the structure points to an area of memory large enough to hold a copy of the counter structure. Prototype
INT4 spectraGetStatus(sSPE_HNDL deviceHandle, sSPE_STATUS *palm)
Inputs
deviceHandle palm
: device Handle (from spectraAdd) : (pointer to) allocated memory
Outputs
palm
: current alarm status
Returns
Success = SPE_SUCCESS
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
101
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Failure = Valid States Side Effects ACTIVE, INACTIVE None
Retrieving Alarm Status for IO block: spectraGetStatusIO
This function reads a given alarm status from the alarm status registers. Prototype
INT4 spectraGetStatusIO(sSPE_HNDL deviceHandle, sSPE_STATUS_IO *palmIO)
Inputs
deviceHandle palmIO
: device Handle (from spectraAdd) : (pointer to) allocated memory
Outputs
palmIO
: current alarm status
Returns
Success = SPE_SUCCESS Failure =
ACTIVE
Valid States Side Effects
None
Retrieving Alarm Status for SOP block: spectraGetStatusSOP
This function reads a given alarm status from the alarm status registers. Prototype
INT4 spectraGetStatusSOP(sSPE_HNDL deviceHandle, sSPE_STATUS_SOP *palmSOP)
Inputs
deviceHandle
: device Handle (from spectraAdd)
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
102
Spectra-622 (PM5313) Driver Manual Application Programming Interface
palmSOP
: (pointer to) allocated memory : current alarm status
Outputs
palmSOP
Returns
Success = SPE_SUCCESS Failure =
ACTIVE
Valid States Side Effects
None
Retrieving Alarm Status for LOP block: spectraGetStatusLOP
This function reads a given alarm status from the alarm status registers. Prototype
INT4 spectraGetStatusLOP(sSPE_HNDL deviceHandle, sSPE_STATUS_LOP *palmLOP)
Inputs
deviceHandle palmLOP
: device Handle (from spectraAdd) : (pointer to) allocated memory
Outputs
palmLOP
: current alarm status
Returns
Success = SPE_SUCCESS Failure =
ACTIVE
Valid States Side Effects
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
103
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Retrieving Alarm Status for RPPS block: spectraGetStatusRPPS
This function reads a given alarm status from the alarm status registers. Prototype
INT4 spectraGetStatusRPPSP(sSPE_HNDL deviceHandle, sSPE_STATUS_RPPS *palmRPPS)
Inputs
deviceHandle palmRPPS
: device Handle (from spectraAdd) : (pointer to) allocated memory
Outputs
palmRPPS
: current alarm status
Returns
Success = SPE_SUCCESS Failure = < SPECTRA-622 ERROR CODE>
ACTIVE
Valid States Side Effects
None
Retrieving Alarm Status for TPPS block: spectraGetStatusTPPS
This function reads a given alarm status from the alarm status registers. Prototype
INT4 spectraGetStatusTPPS(sSPE_HNDL deviceHandle, sSPE_STATUS_TPPS *palmTPPS)
Inputs
deviceHandle palmTPPS
: device Handle (from spectraAdd) : (pointer to) allocated memory
Outputs
palmTPPS
: current alarm status
Returns
Success = SPE_SUCCESS Failure =
ACTIVE
Valid States
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
104
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Side Effects
None
5.21 Device Diagnostics
Verifying Register Access: spectraTestReg
This function verifies the hardware access to the device registers by writing and reading back values. Prototype Inputs Outputs Returns
INT4 spectraTestReg(sSPE_HNDL deviceHandle) deviceHandle
: device Handle (from spectraAdd)
None Success = SPE_SUCCESS Failure = PRESENT None
Valid States Side Effects
Clearing and Setting a Line Loopback: spectraLoopLine
This function clears and sets a Line Loopback (SLLE=1). The spectraLoopLine connects the high speed receive data and clock to the high speed transmit data and clock, and can be used for line side investigations (including clock recovery and clock synthesis). While in this mode, the entire receive path is operating normally. Note: It is up to the USER to perform any tests on the looped data. Prototype
INT4 spectraLoopLine(sSPE_HNDL deviceHandle, UINT2 enable) deviceHandle
Inputs
: device Handle (from spectraAdd)
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
105
Spectra-622 (PM5313) Driver Manual Application Programming Interface
enable
: sets loop if non-zero, else clears loop
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE Will inhibit the flow of active data
Valid States Side Effects
Clearing and Setting a Serial Loopback: spectraLoopSerialDiag
This function clears and sets a Serial Diagnostic Loopback (SDLE=1). It connects the high speed transmit data and clock to the high speed receive data and clock. While in this mode, the entire transmit path is operating normally and data is transmitted on the TXD+/- outputs. Note: It is up to the USER to perform any tests on the looped data. Prototype
INT4 spectraLoopSerialDiag(sSPE_HNDL deviceHandle, UINT2 enable) deviceHandle enable
Inputs
: device Handle (from spectraAdd) : sets loop if non-zero, else clears loop
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE Will inhibit the flow of active data
Valid States Side Effects
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
106
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Clearing and Setting a Parallel Loopback: spectraLoopParaDiag
This function clears and sets a parallel diagnostic loopback (PDLE=1). It connects the byte wide transmit data and clock to the byte wide receive data and clock. While in this mode, the entire transmit path is operating normally and data is transmitted on the TXD+/- outputs. Note: It is up to the USER to perform any tests on the looped data. Prototype Inputs INT4 spectraLoopParaDiag(sSPE_HNDL deviceHandle, UINT2 enable)
deviceHandle enable
: device Handle (from spectraAdd) : sets loop if non-zero, else clears loop
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE Will inhibit the flow of active data
Valid States Side Effects
Clearing and Setting a System-Side Loopback: spectraLoopSysSideLine
This function clears and sets a system-side line loopback (SLLBEN=1). It connects the STS-1 (STM-0/AU3) or equivalent receive stream from the Receive Telecom bus Aligner (RTAL) of the associated RPPS to the Transmit Telecom bus Aligner (TTAL) of the corresponding TPPS. This mode can be used for line side investigations (including clock recovery and clock synthesis) as well as path processing investigations. While in this mode, the entire receive path is operating normally. The SPECTRA-622 may be configured to support the system-side line loopback of up to twelve STS-1 (STM-0/AU3) or equivalent receive streams. Note: It is up to the USER to perform any tests on the looped data. Prototype
INT4 spectraLoopSysSideLine(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 enable) deviceHandle stm1 au3
Inputs
: device Handle (from spectraAdd) : STM-1 index : AU-3 index
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
107
Spectra-622 (PM5313) Driver Manual Application Programming Interface
enable
: sets loop if non-zero, else clears loop
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE Will inhibit the flow of active data
Valid States Side Effects
Clearing and Setting a DS3 Line Loopback: spectraLoopDS3Line
This function clears and sets a DS3 line loopback (DS3LLBEN=1). It connects the DS3 receive stream from the DS3 Mapper DROP side (D3MD) of the associated RPPS to the DS3 Mapper ADD side (D3MA) of the corresponding TPPS. The DS3ADDSEL bit in the SPECTRA-622 TPPS Path and DS3 Configuration register of the TPPS must be set high. This mode can be used for line side investigations (including clock recovery and clock synthesis) as well as DS3 stream processing investigations. While in this mode, the entire receive (DS3) path is operating normally. The SPECTRA-622 may be configured to support the DS3 line loopback of up to twelve DS3 receive streams. Note: It is up to the USER to perform any tests on the looped data. Prototype
INT4 spectraLoopDS3Line(sSPE_HNDL deviceHandle, UINT2 stm1, UINT2 au3, UINT2 enable) deviceHandle stm1 au3 enable
Inputs
: device Handle (from spectraAdd) : STM-1 index : AU-3 index : sets loop if non-zero, else clears loop
Outputs Returns
None Success = SPE_SUCCESS Failure = ACTIVE Will inhibit the flow of active data
Valid States Side Effects
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
108
Spectra-622 (PM5313) Driver Manual Application Programming Interface
5.22 Callback Functions
The SPECTRA-622 driver has the capability to callback to functions within the USER code when certain events occur. These events and their associated callback routine declarations are detailed below. There is no USER code action that is required by the driver for these callbacks - the USER is free to implement these callbacks in any manner or else they can be deleted from the driver. The names given to the callback functions are given as examples only. The addresses of the callback functions invoked by the spectraDPR function are passed during the spectraInit call (inside a DIV). However the USER shall use the exact same prototype. Note: The Application is left responsible for releasing the passed DPV as soon as possible (to avoid running out of DPV buffers) by calling sysSpectraDPVBufferRtn either within the callback function or later inside the Application code.
Callbacks Due to IO Events: cbackSpectraIO
This callback function is provided by the USER and is used by the DPR to report significant IO section events back to the application. This function should be nonblocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. Note: The USER should free the DPV buffer. Prototype Inputs
void cbackSpectraIO(sSPE_USR_CTXT usrCtxt, sSPE_DPV *pdpv) usrCtxt pdpv
: user context (from spectraAdd) : (pointer to) formatted event buffer
Outputs Returns Valid States Side Effects
None None ACTIVE None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
109
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Callbacks Due to TOC Events: cbackSpectraTOC
This callback function is provided by the USER and is used by the DPR to report significant TOC section events back to the application. This function should be nonblocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. Note: The USER should free the DPV buffer. Prototype Inputs
void cbackSpectraTOC(sSPE_USR_CTXT usrCtxt, sSPE_DPV *pdpv) usrCtxt pdpv
: user context (from spectraAdd) : (pointer to) formatted event buffer
Outputs Returns Valid States Side Effects
None None ACTIVE None
Callbacks Due to SOP Events: cbackSpectraSOP
This callback function is provided by the USER and is used by the DPR to report significant SOP section events back to the application. This function should be nonblocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. Note: The USER should free the DPV buffer. Prototype Inputs
void cbackSpectraSOP(sSPE_USR_CTXT usrCtxt, sSPE_DPV *pdpv) usrCtxt pdpv
: user context (from spectraAdd) : (pointer to) formatted event buffer
Outputs
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
110
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Returns Valid States Side Effects
None ACTIVE None
Callbacks Due to SSTB Events: cbackSpectraSSTB
This callback function is provided by the USER and is used by the DPR to report significant SSTB section events back to the application. This function should be nonblocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. Note: The USER should free the DPV buffer. Prototype Inputs
void cbackSpectraSSTB(sSPE_USR_CTXT usrCtxt, sSPE_DPV *pdpv) usrCtxt pdpv
: user context (from spectraAdd) : (pointer to) formatted event buffer
Outputs Returns Valid States Side Effects
None None ACTIVE None
Callbacks Due to LOP Events: cbackSpectraLOP
This callback function is provided by the USER and is used by the DPR to report significant LOP section events back to the application. This function should be nonblocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. Note: The USER should free the DPV buffer.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
111
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Prototype Inputs
void cbackSpectraLOP(sSPE_USR_CTXT usrCtxt, sSPE_DPV *pdpv) usrCtxt pdpv
: user context (from spectraAdd) : (pointer to) formatted event buffer
Outputs Returns Valid States Side Effects
None None ACTIVE None
Callbacks Due to RPPS Events: cbackSpectraRPPS
This callback function is provided by the USER and is used by the DPR to report significant RPPS section events back to the application. This function should be nonblocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. Note: The USER should free the DPV buffer. Prototype Inputs
void cbackSpectraRPPS(sSPE_USR_CTXT usrCtxt, sSPE_DPV *pdpv) usrCtxt pdpv
: user context (from spectraAdd) : (pointer to) formatted event buffer
Outputs Returns Valid States Side Effects
None None ACTIVE None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
112
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Callbacks due to TPPS events: cbackSpectraTPPS
This callback function is provided by the USER and is used by the DPR to report significant TPPS section events back to the application. This function should be nonblocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. Note: The USER should free the DPV buffer. Prototype Inputs
void cbackSpectraTPPS(sSPE_USR_CTXT usrCtxt, sSPE_DPV *pdpv) usrCtxt pdpv
: user context (from spectraAdd) : (pointer to) formatted event buffer
Outputs Returns Valid States Side Effects
None None ACTIVE None
Callbacks Due to WANS Events: cbackSpectraWANS
This callback function is provided by the USER and is used by the DPR to report significant WANS section events back to the application. This function should be nonblocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. Note: The USER should free the DPV buffer. Prototype Inputs
void cbackSpectraWANS(sSPE_USR_CTXT usrCtxt, sSPE_DPV *pdpv) usrCtxt pdpv
: user context (from spectraAdd) : (pointer to) formatted event buffer
Outputs
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
113
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Returns Valid States Side Effects
None ACTIVE None
Callbacks Due to DPGM Events: cbackSpectraDPGM
This callback function is provided by the USER and is used by the DPR to report significant DPGM section events back to the application. This function should be nonblocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. Note: The USER should free the DPV buffer. Prototype Inputs
void cbackSpectraDPGM(sSPE_USR_CTXT usrCtxt, sSPE_DPV *pdpv) usrCtxt pdpv
: user context (from spectraAdd) : (pointer to) formatted event buffer
Outputs Returns Valid States Side Effects
None None ACTIVE None
Callbacks Due to APGM Events: cbackSpectraAPGM
This callback function is provided by the USER and is used by the DPR to report significant APGM section events back to the application. This function should be nonblocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
114
Spectra-622 (PM5313) Driver Manual Application Programming Interface
Note: the USER should free the DPV buffer. Prototype Inputs
void cbackSpectraAPGM(sSPE_USR_CTXT usrCtxt, sSPE_DPV *pdpv) usrCtxt pdpv
: user context (from spectraAdd) : (pointer to) formatted event buffer
Outputs Returns Valid States Side Effects
None None ACTIVE None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
115
Spectra-622 (PM5313) Driver Manual Hardware Interface
6
HARDWARE INTERFACE
The SPECRTA-622 driver interfaces directly with the USER's hardware. In this section, a listing of each point of interface is shown, along with a declaration and any specific porting instructions. It is the responsibility of the USER to connect these requirements into the hardware, either by defining a macro or by writing a function for each item listed. Care should be taken when matching parameters and return values.
6.1
Device I/O
Reading Registers: sysSpectraRead
This function serves as the most basic hardware connection by reading the contents of a specific register location. This Macro should be UINT1 oriented, and should be defined by the user to reflect the target system's addressing logic. There is no need for error recovery in this function. Prototype Inputs Outputs Returns Format
UINT1 sysSpectraRead(UINT1 *addr) addr
: register location to be read
None value read from the addressed register location
#define sysSpectraRead(addr)
Writing Values: sysSpectraWrite
This function serves as the most basic hardware connection by writing the supplied value to the specific register location. This macro should be UINT1 oriented and should be defined by the user to reflect the target system's addressing logic. There is no need for error recovery in this function. Prototype Inputs
void sysSpectraWrite(UINT1 *addr, UINT value) addr
: register location to be read
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
116
Spectra-622 (PM5313) Driver Manual Hardware Interface
Outputs Returns Format
None value read from the addressed register location
#define sysSpectraWrite(addr, value)
6.2
Interrupt Servicing
The porting of an ISR routine between platforms is a rather difficult task. There are many different implementations of these hardware level routines. In this driver, the USER is responsible for installing an interrupt handler (sysSpectraISRHandler) in the interrupt vector table of the system processor. This handler shall call spectraISR for each device that has interrupt servicing enabled, to perform the ISR related housekeeping required by each device. During execution of the API function spectraModuleStart / spectraModuleStop the driver informs the application that it is time to install / uninstall this shell via sysSpectraISRHandlerInstall / sysSpectraISRHandlerRemove, that needs to be supplied by the USER. Note: A device can be initialized with ISR disabled. In that mode, the USER should periodically invoke a provided `polling' routine (spectraPoll) that in turn calls
spectraISR.
Installing the ISR Handler: sysSpectraISRHandlerInstall
This function installs the USER-supplied Interrupt Service Routine (ISR), sysSpectraISRHandler, into the processor's interrupt vector table. Prototype Inputs Outputs Returns Valid States
void sysSpectraISRHandlerInstall(void *func) func
: (pointer to) the function spectraISR
None None None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
117
Spectra-622 (PM5313) Driver Manual Hardware Interface
Format
#define sysSpectraISRHandlerInstall(func)
ISR Handler: sysSpectraISRHandler
This routine is invoked when one or more SPECTRA-622 devices raise the interrupt line to the microprocessor. This routine invokes the driver-provided routine (spectraISR) for each device registered with the driver. Prototype Inputs Outputs Returns Format
void sysSpectraISRHandler(void)
None None None
#define sysSpectraISRHandler()
Removing Handlers: sysSpectraISRHandlerRemove
This function disables Interrupt processing for this device. It removes the USER-supplied Interrupt Service routine (ISR), sysSpectraISRHandler, from the processor's interrupt vector table. Prototype Inputs Outputs Returns Format
void sysSpectraISRHandlerRemove(void)
None None None
#define sysSpectraISRHandlerRemove()
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
118
Spectra-622 (PM5313) Driver Manual Hardware Interface
DPR Task: sysSpectraDPRTask
This routine is installed as a separate task within the RTOS. It runs periodically and retrieves the interrupt status information sent to it by the spectraISRHandler routine, thereafter invoking the spectraDPR routine for the appropriate device. Prototype Inputs Outputs Returns Format
void sysSpectraDPRTask(void)
None None None
#define sysSpectraDPRTask()
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
119
Spectra-622 (PM5313) Driver Manual RTOS Interface
7
RTOS INTERFACE
The SPECTRA-622 driver requires the use of some RTOS resources. In this section, a listing of each required resource is shown, along with a declaration and any specific porting instructions. It is the responsibility of the USER to connect these requirements into the RTOS, either by defining a macro or writing a function for each item listed. Care should be taken when matching parameters and return values.
7.1
Memory Allocation / De-Allocation
Allocating Memory: sysSpectraMemAlloc
This function allocates specified number of bytes of memory. Prototype Inputs Outputs Returns
UINT1 *sysSpectraMemAlloc(UINT4 numBytes) numBytes
: number of bytes to be allocated
None Success = Pointer to first byte of allocated memory Failure = NULL pointer (memory allocation failed)
#define sysSpectraMemAlloc(numBytes)
Format
Freeing Memory: sysSpectraMemFree
This function frees the memory allocated when using the sysSpectraMemAlloc. Prototype Inputs
void sysSpectraMemFree(UINT1 *pfirstByte) pfirstByte
: pointer to first byte of the memory region being de-allocated
Outputs Returns
None None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
120
Spectra-622 (PM5313) Driver Manual RTOS Interface
Format
#define sysSpectraMemFree(pfirstByte)
7.2
Buffer Management
All operating systems provide some sort of buffer system, particularly for use in sending and receiving messages. The following calls, provided by the USER, allow the Driver to Get and Return buffers from the RTOS. It is the USER's responsibility to create any special resources or pools to handle buffers of these sizes during the sysSpectraBufferStart call.
Starting Buffer Management: sysSpectraBufferStart
This function alerts the RTOS that the ISV buffers and DPV buffers are available and should be sized correctly. This may or may not involve the creation of new buffer pools, depending on the RTOS. Prototype Inputs Outputs Returns
INT4 sysSpectraBufferStart(void)
None None Success = SPE_SUCCESS Failure =
#define sysSpectraBufferStart()
Format
Getting DPV Buffers: sysSpectraDPVBufferGet
This function retrieves a buffer from the RTOS. The buffer is used by the DPR code to create a Deferred Processing Vector (DPV). The DPV contains information about the state of the device. This information is passed on to the USER via a callback function. Prototype
sSPE_DPV *sysSpectraDPVBufferGet(void)
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
121
Spectra-622 (PM5313) Driver Manual RTOS Interface
Inputs Outputs Returns
None None Success = (pointer to) a DPV buffer Failure = NULL (pointer)
#define sysSpectraDPVBufferGet()
Format
Getting ISV Buffers: sysSpectraISVBufferGet
This function retrieves a buffer from the RTOS. The buffer is used by the ISR code to create a Interrupt Service Vector (ISV). The ISV contains data transferred from the devices interrupt status registers. Prototype Inputs Outputs Returns
sSPE_ISV *sysSpectraISVBufferGet(void)
None None Success = (pointer to) a ISV buffer Failure = NULL (pointer)
#define sysSpectraISVBufferGet()
Format
Returning DPV Buffers: sysSpectraDPVBufferRtn
This device returns a DPV buffer to the RTOS when the information in the block is no longer needed by the DPR. Prototype Inputs Outputs
void sysSpectraDPVBufferRtn(sSPE_DPV *pdpv) pdpv
: (pointer to) a DPV buffer
None
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
122
Spectra-622 (PM5313) Driver Manual RTOS Interface
Returns Format
None
#define sysSpectraDPVBufferRtn(pdpv)
Returning ISV Buffers: sysSpectraISVBufferRtn
This device returns a ISV buffer to the RTOS when the information in the block is no longer needed by the DPR. Prototype Inputs Outputs Returns Format
void sysSpectraISVBufferRtn(sSPE_ISV *pisv) pisv
: (pointer to) a ISV buffer
None None
#define sysSpectraISVBufferRtn(pisv)
Stopping Buffer Management: sysSpectraBufferStop
This function alerts the RTOS that the Driver no longer needs the ISV buffers or DPV buffers. If any special resources were created to handle these buffers, they can be deleted at this time. Prototype Inputs Outputs Returns Format
void sysSpectraBufferStop(void)
None None None
#define sysSpectraBufferStop()
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
123
Spectra-622 (PM5313) Driver Manual RTOS Interface
7.3
Preemption
Disabling Preemption: sysSpectraPreemptDisable
This routine prevents the calling task from being preempted. If the driver is in interrupt mode, this routine locks out all interrupts as well as other tasks in the system. If the driver is in polling mode, this routine locks out other tasks only.
Prototype Inputs Outputs Returns
INT4 sysSpectraPreemptDisable(void)
None None Preemption key (passed back as an argument in
sysSpectraPreemptEnable)
Format
#define sysSpectraPreemptDisable()
Re-Enabling Preemption: sysSpectraPreemptEnable
This routine allows the calling task to be preempted. If the driver is in interrupt mode, this routine unlocks all interrupts and other tasks in the system. If the driver is in polling mode, this routine unlocks other tasks only. Prototype Inputs
void sysSpectraPreemptEnable(INT4 key)
key
: preemption key (returned by sysSpectraPreemptDisable)
Outputs Returns Format
None None #define sysSpectraPreemptEnable(key)
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
124
Spectra-622 (PM5313) Driver Manual RTOS Interface
7.4
Timers
Suspending a Task Execution: sysSpectraTimerSleep
This function suspends the execution of a driver task for a specified number of milliseconds. Prototype Inputs Outputs Returns Format
void sysSpectraTimerSleep(UINT4 msec) msec
: sleep time in milliseconds
None None
#define sysSpectraTimerSleep(msec)
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
125
Spectra-622 (PM5313) Driver Manual Porting Drivers
8
PORTING DRIVERS
This section outlines how to port the SPECTRA-622 device driver to your hardware and OS platform. However, this manual can offer only guidelines for porting the SPECTRA622 driver because each platform and application is unique.
8.1
Driver Source Files
The C files listed in the following table contain the code for the SPECTRA-622 driver. You may need to modify the code or develop additional code. The code is in the form of constants, macros, and functions. For the ease of porting, the code is grouped into source files (src) and include files (inc). The source files contain the functions and the include files contain the structures, constants and macros. Directory
src
File
spe_api1.c spe_api2.c spe_hw.c spe_isr.c spe_prof.c spe_rtos.c spe_stat.c spe_util.c
Description All the API functions that take care of module, device and profile management All the SPECTRA-622 specific API functions. Hardware interface functions Internal functions that deal with interrupt servicing Internal functions that deal with profiles RTOS interface functions Internal functions that deal with statistics All the remaining internal functions All API headers Driver macros, constants and definitions (such as register mapping and bit masks) SPECTRA-622 error codes Prototype of non-API functions HW interface macros and prototype RTOS interface macros and prototypes driver structures types definitions Sample driver callback functions and example code Prototypes, macros and structures used inside the example code
inc
spe_api.h spe_defs.h spe_err.h spe_fns.h spe_hw.h spe_rtos.h spe_strs.h spe_typs.h
example
spe_app.c spe_app.h
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
126
Spectra-622 (PM5313) Driver Manual Porting Drivers
8.2
Driver Porting Procedures
The following procedures summarize how to port the SPECTRA-622 driver to your platform. The subsequent sections describe these procedures in more detail. To port the SPECTRA-622 driver to your platform: Step 1: Port the driver's RTOS interface (page 127): Step 2: Port the driver's hardware interface (page 128): Step 3: Port the driver's application-specific elements (page 130): Step 4: Build the driver (page 130). Porting Assumptions The following porting assumptions have been made: * * * It is assumed that ram assigned to the Driver's static variables is initialized to ZERO before any Driver function is called. It is assumed that a ram stack of 4K is available to all of the Driver's non-ISR functions and that a ram stack of 1K is available to the Driver's ISR functions. It is assumed that there is no memory management or MMU in the system or that all accesses by the driver, to memory or hardware can be direct.
Step 1: Porting the RTOS interface
The RTOS interface functions and macros consist of code that is RTOS dependent and needs to be modified as per your RTOS's characteristics. To port the driver's OS extensions: 1. Redefine the following macros and functions in the spe_rtos.h file to the corresponding system calls that your target system supports: Service Type Memory Macro Name
sysSpectraMemAlloc sysSpectraMemFree sysSpectraMemCpy sysSpectraMemSet
Description Allocates a memory block Frees a memory block Copies the contents of one memory block to another Fills a memory block with a specified value
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
127
Spectra-622 (PM5313) Driver Manual Porting Drivers
Timer Pre-emption Lock/Unlock
sysSpectraTimerSleep sysSpectraPreemptDisable
Delays the task execution for a given number of milliseconds Disables pre-emption of the currently executing task by any other task or interrupt Re-enables pre-emption of a task by other tasks and/or interrupts
sysSpectraPreemptEnable
2. Modify the example implementation of the buffer management routines provided in the spe_rtos.h file with the corresponding system calls that your target system supports: Service Type Buffer Macro Name
sysSpectraBufferStart sysSpectraBufferStop sysSpectraISVBufferGet sysSpectraISVBufferRtn sysSpectraDPVBufferGet sysSpectraDPVBufferRtn
Description Starts buffer management Stops buffer management Gets an ISV buffer from the ISV buffer queue Returns an ISV buffer to the ISV buffer queue Gets a DPV buffer from the DPV buffer queue Returns a DPV buffer to the DPV buffer queue
3. Define the following constants for your OS-specific services in spe_rtos.h: Task Constant
SPE_DPR_TASK_PRIORITY SPE_DPR_TASK_STACK_SZ SPE_MAX_ISV_BUF
Description Deferred Task (DPR) task priority DPR task stack size, in bytes The queue message depth of the queue used for pass interrupt context between the ISR task and DPR task The queue message depth of the queue used for pass interrupt context between the ISR task and DPR task
Default 85 8192 50
SPE_MAX_DPV_BUF
950
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
128
Spectra-622 (PM5313) Driver Manual Porting Drivers
Step 2: Porting the Hardware Interface
This section describes how to modify the SPECTRA-622 driver for your hardware platform. To port the driver to your hardware platform: 1. Modify the variable type definitions in spe_typs.h. 2. Modify the low-level hardware-dependent functions and macros in the spe_hw.h file. You may need to modify the raw read/write access macros (sysSpectraRead and sysSpectraWrite) to reflect your system's addressing logic. Service Type Register Access Function Name
sysSpectraRead sysSpectraWrite
Description Reads a device register given its real address in memory Writes to a device register given its real address in memory Installs the interrupt handler for the OS Removes the interrupt handler from the OS Interrupt handler for the SPECTRA-622 device Task that calls the SPECTRA-622 DPR
Interrupt
sysSpectraISRHandlerInstall sysSpectraISRHandlerRemove sysSpectraISRHandler sysSpectraDPRTask
3. Define the hardware system-configuration constants in the spe_hw.h file. Modify the following constants to reflect your system's hardware configuration: Device Constant
SPE_MAX_DEVS SPE_MAX_DELAY SPE_MAX_POLL
Description The maximum number of SPECTRA-622 devices that can be supported by the driver Delay between two consecutive polls of a busy bit Maximum number of times a busy bit will be polled before the operation times out
Default 5 100us 100
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
129
Spectra-622 (PM5313) Driver Manual Porting Drivers
Step 3: Porting the Application-Specific Elements
Porting the application-specific elements includes coding the application callback and defining all the constants used by the API. To port the driver's application-specific elements: 1. Modify the base value of SPE_ERR_BASE (default = -300) in spe_err.h. 2. Define the following constants as required by your application in spe_rtos.h: Task Constant
SPE_MAX_INIT_PROFS SPE_MAX_DIAG_PROFS
Description The maximum number of initialization profiles that can be added to the driver The maximum number of diagnostic profiles that can be added to the driver
Default 5 5
3. Code the callback functions according to your application. Example implementations of these callbacks are provided in app.c. The driver will call these callback functions when an event occurs on the device. These functions must conform to the following prototype:
void cbackXX(sSPE_USR_CTXT usrCtxt, void *pdpv)
Step 4: Building the Driver
This section describes how to build the SPECTRA-622 driver. To build the driver: 1. Modify the Makefile to reflect the absolute path of your code, your compiler and compiler options. 2. Choose from among the different compile options supported by the driver as per your requirements. 3. Compile the source files and build the SPECTRA-622 API driver library using your make utility. 4. Link the SPECTRA-622 API driver library to your application code.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
130
Spectra-622 (PM5313) Driver Manual Appendix A: Driver Return Codes
APPENDIX A: DRIVER RETURN CODES
Table 25 describes the driver's return codes. Table 25: Return Codes Return Type
SPE_ERR_MEM_ALLOC SPE_ERR_INVALID_ARG SPE_ERR_INVALID_MODULE_STATE SPE_ERR_INVALID_MIV SPE_ERR_PROFILES_FULL SPE_ERR_INVALID_PROFILE SPE_ERR_INVALID_PROFILE_MODE SPE_ERR_INVALID_PROFILE_NUM SPE_ERR_INVALID_DEVICE_STATE SPE_ERR_DEVS_FULL SPE_ERR_DEV_ALREADY_ADDED SPE_ERR_INVALID_DEV SPE_ERR_INVALID_DIV SPE_ERR_INT_INSTALL SPE_ERR_INVALID_MODE SPE_ERR_INVALID_REG SPE_ERR_POLL_TIMEOUT
Description Memory allocation failure Invalid argument Invalid Module state Invalid Module Initialization Vector Maximum number of profiles already added Invalid profile Invalid profile mode selected Invalid profile number Invalid Device state Maximum number of devices already added Device already added Invalid device handle Invalid Device Initialization Vector Error while installing interrupts Invalid ISR/polling mode Invalid register number Time-out while polling
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
131
Spectra-622 (PM5313) Driver Manual Appendix B: Coding Conventions
APPENDIX B: CODING CONVENTIONS
This section describes the coding conventions used in the implementation of all PMC driver software.
Variable Type Definitions
Table 26: Variable Type Definitions
Type
UINT1 UINT2 UINT4 INT1 INT2 INT4
Description
unsigned integer - 1 byte unsigned integer - 2 bytes unsigned integer - 4 bytes signed integer - 1 byte signed integer - 2 bytes signed integer - 4 bytes
Naming Conventions
Table 27 presents a summary of the naming conventions followed by all PMC driver software. A detailed description is then given in the following sub-sections. The names used in the drivers are verbose enough to make their purpose fairly clear. This makes the code more readable. Generally, the device's name or abbreviation appears in prefix. Table 27: Naming Conventions
Type
Macros Constants Structures
Case
Naming convention
Examples
mSPE_SLICE_OFFSET SPE_MAX_REGS
Uppercase prefix with "m" and device abbreviation Uppercase prefix with device abbreviation
Hungarian prefix with "s" and device sSPE_DDB Notation abbreviation
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
132
Spectra-622 (PM5313) Driver Manual Appendix B: Coding Conventions
Type
API Functions Porting Functions Other Functions Variables
Case
Naming convention
Examples
spectraAdd() sysSpectraRead() myOwnFunction() maxDevs pmaxDevs spectraMdb
Hungarian prefix with device name Notation Hungarian prefix with "sys" and Notation device name Hungarian Notation Hungarian Notation
Pointers to Hungarian prefix variable name with variables Notation "p" Global variables Hungarian prefix with device name Notation
Macros
The following list identifies the marcro conventions used in the driver code: * * * * Macro names can be uppercase. Words can be separated by an underscore. The letter `m' in lowercase is used as a prefix to specify that it is a macro, then the device abbreviation appears. Example: mSPE_SLICE_OFFSET is a valid name for a macro.
Constants
The following list identifies the constants conventions used in the driver code: * * * * Constant names can be uppercase. Words can be separated by an underscore. The device abbreviation can appear as a prefix. Example: SPE_MAX_REGS is a valid name for a constant.
Structures
The following list identifies the structures conventions used in the driver code: * * Structure names can be uppercase. Words can be separated by an underscore.
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
133
Spectra-622 (PM5313) Driver Manual Appendix B: Coding Conventions
* *
The letter `s' in lowercase can be used as a prefix to specify that it is a structure, then the device abbreviation appears. Example: sSPE_DDB is a valid name for a structure.
Functions
API Functions * * * Naming of the API functions follows the hungarian notation. The device's full name in all lowercase can be used as a prefix. Example: spectraAdd() is a valid name for an API function.
Porting Functions Porting functions correspond to all function that are HW and/or RTOS dependant. * * * * Naming of the porting functions follows the hungarian notation. The `sys' prefix can be used to indicate a porting function. The device's name starting with an uppercase can follow the prefix. Example: sysSpectraRead() is a hardware / RTOS specific.
Other Functions * * Other Functions are all the remaining functions that are part of the driver and have no special naming convention. However, they can follow the hungarian notation. Example: myOwnFunction() is a valid name for such a function.
Variables
* * Naming of variables follows the hungarian notation. A pointer to a variable shall use `p' as a prefix followed by the variable name unchanged. If the variable name already starts with a `p', the first letter of the variable name may be capitalized, but this is not a requirement. Double pointers might be prefixed with `pp', but this is not required. Global variables are identified with the device's name in all lowercase as a prefix. Examples: maxDevs is a valid name for a variable, pmaxDevs is a valid name for a pointer to maxDevs, and spectraMdb is a valid name for a global variable. Note: Both pprevBuf and pPrevBuf are accepted names for a pointer to the prevBuf variable, and that both pmatrix and ppmatrix are accepted names for a double pointer to the variable matrix.
* * *
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
134
Spectra-622 (PM5313) Driver Manual Appendix B: Coding Conventions
File Organization
Table 28 presents a summary of the file naming conventions. All file names must start with the device abbreviation, followed by an underscore and the actual file name. File names should convey their purpose with a minimum amount of characters. If a file size is getting too big one might separate it into two or more files, providing that a number is added at the end of the file name (e.g. spe_api1.c or spe_api2.c). There are 4 different types of files: * * * * The API file containing all the API functions The hardware file containing the hardware dependant functions The RTOS file containing the RTOS dependant functions The other files containing all the remaining functions of the driver
Table 28: File Naming Conventions
File Type
API Hardware Dependant RTOS Dependant Other
File Name
spe_api1.c, spe_api.h spe_hw.c, spe_hw.h spe_rtos.c, spe_rtos.h spe_isr.c, spe_defs.h
API Files
* * The name of the API files must start with the device abbreviation followed by an underscore and `api'. Eventually a number might be added at the end of the name. Examples: spe_api1.c is the only valid name for the file that contains the first part of the API functions, spe_api.h is the only valid name for the file that contains all of the API functions headers.
Hardware Dependent Files
* The name of the hardware dependent files must start with the device abbreviation followed by an underscore and `hw'. Eventually a number might be added at the end of the file name. Examples: spe_hw.c is the only valid name for the file that contains all of the hardware dependent functions, spe_hw.h is the only valid name for the file that contains all of the hardware dependent functions headers. RTOS Dependant Files
135
*
*
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
Spectra-622 (PM5313) Driver Manual Appendix B: Coding Conventions
*
The name of the RTOS dependant files must start with the device abbreviation followed by an underscore and `rtos'. Eventually a number might be added at the end of the file name. Examples: spe_rtos.c is the only valid name for the file that contains all of the RTOS dependent functions, spe_rtos.h is the only valid name for the file that contains all of the RTOS dependent functions headers.
*
Other Driver Files
* The name of the remaining driver files must start with the device abbreviation followed by an underscore and the file name itself, which should convey the purpose of the functions within that file with a minimum amount of characters. Examples: spe_isr.c is a valid name for a file that would deal with interrupt servicing, spe_defs.h is a valid name for the header file that conatins all the driver's definitions.
*
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
136
Spectra-622 (PM5313) Driver Manual List of Terms
LIST OF TERMS
APPLICATION: Refers to protocol software used in a real system as well as validation software written to validate the SPECTRA-622 driver on a validation platform. API (Application Programming Interface): Describes the connection between this MODULE and the USER's Application code. ISR (Interrupt Service Routine): A common function for intercepting and servicing DEVICE events. This function is kept as short as possible because an Interrupt preempts every other function starting the moment it occurs and gives the service function the highest priority while running. Data is collected, Interrupt indicators are cleared, and the function ended. DPR (Deferred Processing Routine): This function is installed as a task, at a USER configurable priority, that serves as the next logical step in Interrupt processing. Data that was collected by the ISR is analyzed and then calls are made into the Application to inform it of the events that caused the ISR in the first place. Because this function is operating at the task level, the USER can decide on its importance in the system, relative to other functions. DEVICE: A single SPECTRA-622 Integrated Circuit. There can be many Devices; all served by this ONE Driver MODULE * DIV (DEVICE Initialization Vector): A structure passed from the API to the DEVICE during initialization; it contains parameters that identify the specific modes and arrangements of the physical DEVICE being initialized. DDB (DEVICE Data Block): A structure that holds the Configuration Data for each DEVICE.
*
MODULE: All of the code that is part of this driver; there is only ONE instance of this MODULE connected to one or more SPECTRA-622 chips. * MIV (MODULE Initialization Vector): Structure passed from the API to the MODULE during initialization; it contains parameters that identify the specific characteristics of the Driver MODULE being initialized. MDB (MODULE Data Block): A structure that holds the Configuration Data for this MODULE.
*
RTOS (Real Time Operating System): The host for this driver
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
137
Spectra-622 (PM5313) Driver Manual Acronyms
ACRONYMS
API: Application programming interface APGM: Add bus PRBS Generator and Monitor DDB: Device data block DIV: Device initialization vector DPGM: Drop bus PRBS Generator and Monitor DPR: Deferred processing routine DPV: Deferred processing (routine) vector FIFO: First in, first out IO: Input/Output ISR: Interrupt service routine ISV: Initialization service (routine) vector LOP: Line overhead processor MDB: Module data block MIV: Module initialization vector PRBS: Pseudo random byte sequence RING: RING control ports RPPS: Receive path processing slice RTOS: Real-time operating system SOP: Section overhead processor SSTB: Sonet/SDH section trace buffer TOC: Transport overhead controller TPPS: Receive path processing slice WANS: WAN synchronization controller
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
138
Spectra-622 (PM5313) Driver Manual INDEX
INDEX
A
ackActiv, 44 Activating a Device, 64 addControlActi, 45 addDataActiv, 45 Adding a Device, 61 addr, 116, 117 Alarm, Status and Statistics Functions, 97 Allocating Memory, 120 APGM ... See Add Bus PRBS Generator and Monitor, 21, 31, 32, 35, 36, 37, 43, 44, 89, 92, 114, 138 APGM Functions
apgmGenEna, 36 apgmGenSig, 41 apgmMonEna, 36 apgmMonErr, 41 apgmMonSig, 41 apgmMonSync, 41
API Files, 135 Application Programming Interface, 16, 56 aptr, 80 au3, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 90, 91, 92, 93, 107, 108
cbackSpectraAPGM, 114, 115 cbackSpectraDPGM, 114 cbackSpectraIO, 109 cbackSpectraLOP, 111, 112 cbackSpectraRPPS, 112 cbackSpectraSOP, 110 cbackSpectraSSTB, 111 cbackSpectraTOC, 110 cbackSpectraTPPS, 113 cbackSpectraWANS, 113 cbackSSTB, 30, 31, 32, 43 cbackTOC, 30, 31, 32, 43 cbackTPPS, 30, 31, 32, 44 cbackWANS, 30, 31, 32, 44 cbackXX, 130
Callbacks
Callbacks Due to APGM Events, 114 Callbacks Due to DPGM Events, 114 Callbacks Due to IO Events, 109 Callbacks Due to LOP Events, 111 Callbacks Due to RPPS Events, 112 Callbacks Due to SOP Events, 110 Callbacks Due to SSTB Events, 111 Callbacks Due to TOC Events, 110 Callbacks Due to WANS Events, 113
Calling spectraDPR, 27 Calling spectraPoll, 28 CFG_CNT, 50 cfgAPGM, 37, 43 cfgCnt, 43, 97 cfgDPGM, 37, 43 cfgIO, 34, 42 cfgLOP, 34, 43 cfgRING, 35, 43 cfgRPPS, 34, 43 cfgSOP, 34, 43 cfgSSTB, 34, 43 cfgTOC, 34, 42 cfgTPPS, 34, 43 cfgWANS, 35, 43 Clearing and Setting
B
baseAddr, 42, 61 Buffer Management, 121 Building the Driver, 130
C
Callback Functions, 109
cbackAPGM, 30, 31, 32, 44 cbackDPGM, 30, 31, 32, 44 cbackIO, 30, 31, 32, 43 cbackLOP, 30, 31, 32, 43 cbackRPPS, 30, 31, 32, 43 cbackSOP, 30, 31, 32, 43
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
139
Spectra-622 (PM5313) Driver Manual INDEX
DS3 Line Loopback, 108 Line Loopback, 105 Parallel Loopback, 107 Serial Loopback, 106 System-Side Loopback, 107
Clearing the Interrupt Mask, 95 clock77, 33 Closing the Driver Module, 14, 56 Coding Conventions, 132 Configuring Diagnostics, 89 Configuring Statistical Counts, 97 Constants, 29, 132, 133 Creating a Diagnostic Profile, 60 Creating an Initialization Profile, 58
Disabling Preemption, 124 DPGM Functions
dpgmGenEna, 36 dpgmGenSig, 41 dpgmMonEna, 36 dpgmMonErr, 41 dpgmMonSig, 41 dpgmMonSync, 41
DPR ...See Deferred Processing Routine, 17 DPR Task, 119 DPV ...See Deferred Processing Routine Vector, 54, 55 Driver
D
Data Structures, 29 dckActiv, 44 DDB ...See Device Data Block, 42 deferred processing
routine, 137
Deferred Processing Routine, 15, 21, 54, 96 Deferred Processing Vector, 54, 55, 121 Deleting a Device, 62 Deleting a Diagnostic Profile, 61 Deleting an Initialization Profile, 59 Device
External Interfaces, 16 Functions and Features, 14 Hardware Interface, 17 Porting Procedures, 127 Porting Quick Start, 13 Return Codes, 131 Software States, 22 Source Files, 126
driver library, 130 drv, 126 DS3, 19, 20, 78, 83, 108 ds3tdatActiv, 49 ds3ticlkActiv, 49
Activation and De-Activation, 64 Addition and Deletion, 61 Diagnostics, 105 Initialization, 14, 29, 30, 63, 131 Management, 25 Reading and Writing, 66 States, 23, 66
deviceHandle, 54, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 101, 105, 106, 107, 108 devicePoll, 30 DIAG_PROF, 35 diagMode, 35 Diagnostic Profile, 35, 60
E
erdiv, 48 errDevice, 42, 55, 62 errModule, 41, 55
F
File Naming Conventions, 135 Forcing a Pointer Value, 80 Forcing a Resynchronization, 91, 93 Forcing Bit Errors, 90, 92 Forcing DS3 AIS, 78, 83 Forcing Errors in the A1 Byte, 71 Forcing Errors in the B1 Byte, 72 Forcing Errors in the B3 Byte, 80 Forcing Errors in the H4 Byte, 77, 82 Forcing Generation of a New PRBS, 90, 92
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
140
Spectra-622 (PM5313) Driver Manual INDEX
Forcing Loss-Of-Pointer, 76 Forcing Loss-Of-Signal, 72 Forcing Out-of-Frame, 70 Forcing Path AIS, 79 Forcing Phase Reacquisitions, 88 Forcing Tributary Path AIS, 78, 83 Freeing Memory, 120
G
Getting DPV Buffers, 121 Getting ISV Buffers, 122 Getting the Interrupt Mask, 93 Global Variable, 55
ISR ... see Interrupt Service Routine, 17, 21, 26, 27, 29, 30, 31, 32, 37, 43, 54, 57, 94, 95, 117, 118, 122, 127, 128, 131, 138 ISR Enable/Disable Mask, 37 ISR Handler, 118 ISR Mask, 37 ISV ... See Initialization Service Routine Vector, 54
L
Line Overhead Processor, 18 Line Overhead Status, 47 lineSideMode, 33 LOP ... See Line Overhead Processor, 47 lopBipe, 38 lopBlkBip, 51 lopBlkRei, 50 lopCoaps, 38 lopLais, 38 lopLrdi, 38 lopLrei, 38 lopPsbf, 38 lopSd, 38 lopSdber, 38 lopSf, 38 lopSfber, 38 lopZ1S1, 38
H
Hardware Dependent Files, 135 Hardware Interface, 116
I
inc, 13, 126 INIT_PROF, 31 Initialization Profile, 31, 32, 58 Initializing a Device, 63 initMode, 30, 32 Input/Output, 18, 138 Input/Output Status, 44 Inserting Line AIS, 71 Inserting Line Remote Defect Indication, 73 Installing the ISR Handler, 117 Interrupt Service
M
Macros, 132, 133 Makefile, 130 maxDevs, 29, 30, 41 maxDiagProfs, 30, 41 maxInitProfs, 30, 41 MDB ...See Module Data Block, 41 Memory Allocation / De-Allocation, 120 MIV ... See Module Initialization Vector, 29 Modifying the S1 Byte, 69 Modifying the Z0 Byte, 68 Module
Functions, 93 Routine, 21, 96, 117 Vector, 27, 28, 54, 122
Interrupt service routine, 138 Interrupt Servicing, 15, 26, 117 interrupts
service routine, 137
IO ... See Input/Output, 44 ioCrsiRool, 37 ioCspiRool, 37 ioDool, 37 ioLos, 37 ioScpife, 37 ioScpire, 37
Activation, 57 Data Block, 21, 23, 41, 55, 56 Initialization, 23, 29, 30, 56, 131
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
141
Spectra-622 (PM5313) Driver Manual INDEX
Initialization Vector, 23, 29, 30, 56, 131 Management, 24 States, 22
msec, 125
Application Interface, 130 Drivers, 126 Hardware Interface, 129 RTOS interface, 127
ppblk, 34, 36 ppblock, 33, 36 pperrDevice, 61, 62 ppmask, 33, 34, 36 ppmdb, 56 pProfile, 58, 59, 60 pProfileNum, 58, 60 Preemption, 124 prei, 82 Processing Flows, 24 Profile Management, 58 profileNum, 42, 58, 59, 60, 61, 63, 89 psize, 33, 36 pstartReg, 33, 34, 36, 37 ptr, 49
N
Naming Conventions, 132 ndf, 81 NDF_enable, 39, 40 new_point, 39, 40 numBlocks, 33, 34, 36 numBytes, 120 numDevs, 41
O
Opening the Driver Module, 14, 56 Other Driver Files, 136
P
pblkSize, 34, 36 pblock, 67, 68 pddb, 42, 55 pdiagData, 35, 36, 37 pdiagProfs, 42 pdiv, 63 pdpv, 109, 110, 111, 112, 113, 114, 115, 122, 123, 130 pdsb, 101 perrDevice, 61 pfirstByte, 120, 121 piclkActiv, 45 pinActiv, 44 pinitData, 31, 32, 33, 34 pinitProfs, 42 pisv, 96, 123 pJ0, 73 pJ1, 76 pK1, 75 pK2, 75 pmask, 68, 94, 95 pmdb, 30 pmiv, 56 Polling Interrupt Status Registers, 95 pollISR, 30, 31, 32, 43 Porting
R
Reading from a Device Register, 66 Reading the Received K1 and K2 Bytes, 75 Reading the S1 Byte, 69 Receive / Transmit Line Overhead Processor (RLOP/TLOP), 20, 34, 43, 73 Receive / Transmit Section Overhead Processor (RSOP/TSOP), 20, 34, 43, 70 Receive Path Processing Slice, 18 Receive Path Processing Slice (RPPS), 20, 34, 43, 47, 76 Receive Path Status, 47 Re-Enabling Preemption, 124 refclkActiv, 44 regNum, 66 Removing Handlers, 118 Resetting a Device, 64 Retrieving
Alarm Status, 101 and Setting the Path Trace Messages, 76 and Setting the Section Trace Messages, 73
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
142
Spectra-622 (PM5313) Driver Manual INDEX
Diagnostic Profile, 60 Initialization Profile, 59
Return Codes, 131 Returning
DPV Buffers, 122 ISV Buffers, 123
RING ... See RING Control Ports, 45 Ring Control Ports (RING), 20, 45, 87 Ring Control Ports Status, 45 ringEna, 33 RPPS, 31, 32, 34, 43, 48, 107, 108, 112 rppsAu3LopCon, 39 rppsAu3PaisCon, 39 rppsBipe, 39 rppsBlkBip, 51 rppsBlkRei, 51 rppsComa, 39 rppsDiscopa, 39 rppsDpje, 39 rppsErdi, 39 rppsEse, 39 rppsIllreq, 39 rppsInvNdf, 39 rppsIsf, 39 rppsLom1, 38 rppsLom2, 39 rppsLop1, 38 rppsLop2, 39 rppsLopCon, 39 rppsMonrs, 51 rppsNdf, 39 rppsNewPtr, 39 rppsNse, 39 rppsOfl, 40 rppsPais1, 39 rppsPais2, 39 rppsPaisCon, 39 rppsPerdi, 39 rppsPrdi1, 39 rppsPrdi2, 39 rppsPrei, 39 rppsPse, 39 rppsPslm, 39 rppsPslu, 39 rppsRpslm, 40
rppsRpslu, 40 rppsRtim, 39 rppsRtiu, 40 rppsTim, 38 rppsTiu, 38 rppsTiu2, 39 rppsUfl, 40
S
scpi, 45 Section Overhead Processor, 18 Sending Line AIS Maintenance Signal, 87 Sending Line RDI Maintenance Signal, 88 Setting the Interrupt Mask, 94 Software Architecture, 16 Software States, 22 SONET / SDH Section Trace Buffer (SSTB), 20, 73 sopBipe, 38 sopBlkBip, 50 sopLof, 38 sopLos, 38 sopOof, 38 source files, 130 SPE_ACTIVE, 29, 42 spe_api.h, 126 spe_api1.c, 126 spe_api2.c, 126 SPE_COMP, 30, 32, 33, 35, 36 spe_defs.h, 126 SPE_DEV_STATE, 42 SPE_DPR_EVENT, 55 SPE_DPR_TASK_PRIORITY, 128 SPE_DPR_TASK_STACK_SZ, 128 spe_err.h, 126, 130 SPE_ERR_BASE, 130 SPE_ERR_DEV_ALREADY_ADDED, 131 SPE_ERR_DEVS_FULL, 131 SPE_ERR_INT_INSTALL, 131 SPE_ERR_INVALID_ARG, 131 SPE_ERR_INVALID_DEV, 131 SPE_ERR_INVALID_DEVICE_STATE, 131
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
143
Spectra-622 (PM5313) Driver Manual INDEX
SPE_ERR_INVALID_DIV, 131 SPE_ERR_INVALID_MIV, 131 SPE_ERR_INVALID_MODE, 131 SPE_ERR_INVALID_MODULE_STATE, 131 SPE_ERR_INVALID_PROFILE, 131 SPE_ERR_INVALID_PROFILE_MODE, 131 SPE_ERR_INVALID_PROFILE_NUM, 131 SPE_ERR_INVALID_REG, 131 SPE_ERR_MEM_ALLOC, 131 SPE_ERR_POLL_TIMEOUT, 131 SPE_ERR_PROFILES_FULL, 131 SPE_FAILURE, 55 spe_fns.h, 126 SPE_FRM, 30, 32, 34, 35, 37 spe_hw.c, 126 spe_hw.h, 126, 129 SPE_INACTIVE, 29, 42 spe_isr.c, 126 SPE_ISR_MODE, 30 SPE_MAX_DELAY, 129 SPE_MAX_DEVS, 29, 129 SPE_MAX_DIAG_PROFS, 130 SPE_MAX_DPV_BUF, 128 SPE_MAX_INIT_PROFS, 130 SPE_MAX_ISV_BUF, 128 SPE_MAX_POLL, 129 SPE_MOD_IDLE, 29, 42 SPE_MOD_READY, 29, 42 SPE_MOD_START, 29, 42 SPE_MOD_STATE, 42 SPE_MODE, 30, 32, 35 SPE_NORM, 30, 32, 35, 36 SPE_POLL, 30, 43 SPE_POLL_MODE, 30 SPE_PRESENT, 29, 42 spe_prof.c, 126 spe_rtos.c, 126 spe_rtos.h, 126, 127, 128, 130 SPE_START, 29, 42 spe_stat.c, 126 spe_strs.h, 126
SPE_SUCCESS, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 97, 101, 105, 106, 107, 108, 121 spe_typs.h, 126, 129 spe_util.c, 126 spectraActivate, 64, 65 spectraAdd, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 101, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115 spectraAddDiagProfile, 35, 60 spectraAddInitProfile, 30, 31, 58 spectraAPGMGenForceErr, 92 spectraAPGMGenRegen, 92 spectraAPGMMonResync, 93 spectraAPGMonResync, 93 spectraCfgStats, 97 spectraClearMask, 37, 95 spectraDeActivate, 65 spectraDelete, 27, 56, 62 spectraDeleteDiagProfile, 61 spectraDeleteInitProfile, 59 spectraDiagCfg, 89 spectraDPGMGenForceErr, 90 spectraDPGMGenRegen, 90 spectraDPGMMonResync, 91 spectraDPGMonResync, 91 spectraDPR, 21, 26, 27, 28, 96, 109, 119 spectraGetDiagProfile, 60 spectraGetInitProfile, 59 spectraGetMask, 37, 93, 94 spectraGetStats, 101 spectraInit, 30, 63, 109 spectraISR, 21, 26, 27, 28, 96, 117, 118 spectraISRHandler, 119 spectraLoopDS3Line, 108 spectraLoopLine, 105 spectraLoopParaDiag, 107 spectraLoopSerialDiag, 106 spectraLoopSysSideLine, 107
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
144
Spectra-622 (PM5313) Driver Manual INDEX
spectraLOPDiagB2, 74 spectraLOPInsertLineRDI, 73, 74 spectraLOPReadK1K2, 75 spectraLOPWriteK1K2, 75 spectraMdb, 55 spectraModuleClose, 56 spectraModuleOpen, 29, 56 spectraModuleStart, 57, 117 spectraModuleStop, 57, 58, 117 spectraPathTraceMsg, 76 spectraPoll, 28, 95, 117 spectraRead, 66 spectraReadBlock, 67 spectraReset, 64 spectraRINGLineAISControl, 87 spectraRINGLineRDIControl, 88 spectraRPPSDiagH4, 77 spectraRPPSDiagLOP, 76, 77 spectraRPPSDs3AisGen, 78 spectraRPPSInsertTUAIS, 78, 83 spectraSectionTraceMsg, 73 spectraSetMask, 37, 94 spectraSOPDiagB1, 72 spectraSOPDiagFB, 71 spectraSOPDiagLOS, 72 spectraSOPForceOOF, 70 spectraSOPInsertLineAIS, 71 spectraTestReg, 105 spectraTOCReadS1, 69 spectraTOCWriteS1, 69 spectraTOCWriteZ0, 68 spectraTPPSDiagB3, 80 spectraTPPSDiagH4, 82 spectraTPPSDs3AisGen, 83 spectraTPPSForceTxPtr, 80 spectraTPPSInsertNDF, 81 spectraTPPSInsertPAIS, 79 spectraTPPSInsertPREI, 81 spectraTPPSInsertTUAIS, 83 spectraTPPSWriteC2, 84 spectraTPPSWriteF2, 85 spectraTPPSWriteJ1, 84 spectraTPPSWriteZ3, 86 spectraTPPSWriteZ4, 86 spectraTPPSWriteZ5, 87 spectraUpdate, 63
spectraWANSForceReac, 88 spectraWrite, 66 spectraWriteBlock, 68 src, 13, 126 sSPE_CBACK, 31, 32, 43, 44 sSPE_CFG_APGM, 35, 37, 43 sSPE_CFG_CNT, 43, 50, 97 sSPE_CFG_DPGM, 35, 37, 43 sSPE_CFG_IO, 34, 42 sSPE_CFG_LOP, 34, 43 sSPE_CFG_RING, 35, 43 sSPE_CFG_RPPS, 34, 43 sSPE_CFG_SOP, 34, 43 sSPE_CFG_SSTB, 34, 43 sSPE_CFG_TOC, 34, 42 sSPE_CFG_TPPS, 34, 43 sSPE_CFG_WANS, 35, 43 sSPE_CFG_XXX, 34, 37 sSPE_DDB, 42 sSPE_DIAG_DATA_COMP, 36 sSPE_DIAG_DATA_FRM, 37 sSPE_DIAG_DATA_NORM, 36 sSPE_DIAG_PROF, 35, 42, 60 sSPE_DIV, 30, 31, 63 sSPE_DPV, 55, 109, 110, 111, 112, 113, 114, 115, 121, 122 sSPE_HNDL, 54, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 101, 105, 106, 107, 108 sSPE_INIT_DATA_COMP, 31, 32, 34, 35 sSPE_INIT_DATA_FRM, 31, 32, 34, 35 sSPE_INIT_DATA_NORM, 31, 32, 33, 35 sSPE_INIT_PROF, 32, 42, 58, 59 sSPE_ISV, 54, 96, 122, 123 sSPE_MASK, 37, 54, 94, 95 sSPE_MDB, 41, 56 sSPE_MIV, 30, 56 sSPE_POLL, 31, 32 sSPE_STAT_CNT, 52 sSPE_STAT_IO, 44 sSPE_STAT_LOP, 47 sSPE_STAT_RPPS, 47
145
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
Spectra-622 (PM5313) Driver Manual INDEX
sSPE_STAT_TPPS, 49 sSPE_USR_CTXT, 42, 109, 110, 111, 112, 113, 114, 115, 130 SSTB, 31, 32, 34, 43, 111, 138 sstbRtim, 38 sstbRtiu, 38 Starting Buffer Management, 121 Starting the Driver Module, 14, 57 startRegNum, 67, 68 stateDevice, 29, 42, 55 stateModule, 29, 42, 55 Statistic Counters, 50, 51, 52 Stopping Buffer Management, 123 Stopping the Driver Module, 57 Structures
T
Timers, 125 TOC, 138 tocLais, 38 tocLof, 38 tocLos, 38 tocLrdi, 38 tocOof, 38 tocRdool, 38 tocTrool, 38 tpais, 49 TPPS, 138 tppsAu3LopCon, 40 tppsAu3PaisCon, 40 tppsBipe, 40 tppsComa, 40 tppsDiscopa, 40 tppsEse, 40 tppsInvNdf, 40 tppsIsf, 40 tppsLom1, 40 tppsLom2, 40 tppsLop1, 40 tppsLop2, 40 tppsLopCon, 40 tppsNdf, 40 tppsNewPtr, 40 tppsNse, 40 tppsOfl, 41 tppsPais1, 40 tppsPais2, 40 tppsPaisCon, 40 tppsPje, 40 tppsPrei, 40 tppsPse, 40 tppsUfl, 41 Transmit Path Processing Slice, 18, 20, 34, 43, 49, 79 Transmit Path Status, 49 Transport Overhead Controller, 18, 19, 34, 42, 68
In the Driver's Allocated Memory, 41 Passed by the Application, 29 Passed Through RTOS Buffers, 54
Suspending a Task Execution, 125 sysSideMode, 33 sysSpectraBufferStart, 121, 128 sysSpectraBufferStop, 123, 128 sysSpectraDPRTask, 26, 27, 28, 96, 119, 129 sysSpectraDPVBufferGet, 121, 122, 128 sysSpectraDPVBufferRtn, 109, 122, 123, 128 sysSpectraISRHandler, 26, 27, 28, 96, 117, 118, 129 sysSpectraISRHandlerInstall, 27, 117, 118, 129 sysSpectraISRHandlerRemove, 117, 118, 129 sysSpectraISVBufferGet, 122, 128 sysSpectraISVBufferRtn, 123, 128 sysSpectraMemAlloc, 120, 127 sysSpectraMemCpy, 127 sysSpectraMemFree, 120, 121, 127 sysSpectraMemSet, 127 sysSpectraPreemptDisable, 124, 128 sysSpectraPreemptEnable, 124, 128 sysSpectraRead, 66, 67, 116, 129 sysSpectraTimerSleep, 125, 128 sysSpectraWrite, 66, 68, 116, 117, 129
U
Updating the Configuration of a Device, 63
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
146
Spectra-622 (PM5313) Driver Manual INDEX
usrCtxt, 42, 61, 109, 110, 111, 112, 113, 114, 115, 130
V
Variable Type Definitions, 132 Variables, 133, 134 Verifying Register Access, 105
W
WAN Synchronization Controller, 18, 20, 88 WANS, 138 wansEna, 33 wansInt, 41 Writing
a Block of Registers, 68 the C2 Byte, 84 the F2 Byte, 85 the J1 Byte, 84 the Path Remote Error Indication Count, 81 the Z3 Byte, 86 the Z4 Byte, 86 the Z5 Byte, 87 to a Device, 66 to New Data Flag Bits, 81 to Transmitted K1 and K2 Bytes, 75 Values, 116
Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID PMC-1991254 Issue 2
147

▲Up To Search▲

Price & Availability of 1991254

	To Download 1991254 Datasheet File
If you can't view the Datasheet, Please click here to try to view without PDF Reader .